Analytics API

The Analytics API lets you retrieve workspace metrics programmatically using the same data that powers the in-app analytics dashboards. All queries are scoped to the workspace identified by your API key.

For interactive endpoint documentation with request/response examples, see the API reference.

Authentication follows the same API key mechanism used across all v1 endpoints — refer to the API reference for details.

Endpoint

GET /v1/analytics/{metric}

Path parameter

Parameter	Type	Description
`metric`	string	The analytics metric to retrieve. See Available Metrics for all valid values.

Query parameters

Parameter	Type	Required	Description
`time_start`	ISO 8601 datetime	Yes	Start of the time range. Must include a timezone offset (e.g. `2026-01-01T00:00:00Z`). Must be before `time_end`.
`time_end`	ISO 8601 datetime	Yes	End of the time range. Must include a timezone offset.
`page`	integer	No	Page number for paginated metrics (1-based).
`page_size`	integer	No	Number of items per page for paginated metrics. Default: 50. Max: 200.

Time range resolution

The API automatically adjusts aggregation granularity based on the requested range:

More than 3 days → daily buckets
3 days or less → hourly buckets

Rate limits

5 requests per second per workspace.

Response format

All metrics return an AnalyticsResponse object with two fields:

Field	Type	Description
`type`	string	One of `simple`, `table`, `barchart`, `horizontal-barchart`, or `empty`
`value`	object	The metric data. Shape depends on `type` (see below).

`simple` — a single scalar value

{
  "type": "simple",
  "value": {
    "value": 1234,
    "prefix": null,
    "suffix": " runs"
  }
}

Field	Description
`value`	The numeric or string value
`prefix`	Optional string displayed before the value (e.g. `"€"`). For an amount of money it is the symbol of `currency`.
`suffix`	Optional string displayed after the value (e.g. `" runs"`)
`currency`	Set when `value` is an amount of money: `"USD"`, `"EUR"` or `"GBP"`. See Currency of cost metrics.
`cost_details`	Set on cost metrics: the cost object behind `value`

`barchart` — time-series data

{
  "type": "barchart",
  "value": {
    "values": [
      { "name": "2026-01-15", "values": { "runs": 42 }, "value_mapping": null },
      { "name": "2026-01-16", "values": { "runs": 37 }, "value_mapping": null }
    ]
  }
}

Each item in values represents one time bucket. The keys inside values are metric-specific series names.

`table` — tabular summary

{
  "type": "table",
  "value": {
    "headings": ["Model", "Tokens", "Cost"],
    "rows": [
      { "Model": "gpt-4o", "Tokens": 50000, "Cost": { "value": 0.25, "currency": "EUR", ... } }
    ],
    "prefixes": null,
    "suffixes": null
  }
}

`horizontal-barchart` — ranked distribution

Same shape as table, displayed as a horizontal bar chart in the UI.

`empty`

Returned when there is no data for the requested time range.

Error responses

400 — invalid time range

{ "detail": "time_start must be before time_end" }

422 — validation error (e.g. page_size out of bounds)

{
  "detail": [
    {
      "loc": ["query", "page_size"],
      "msg": "ensure this value is less than or equal to 200",
      "type": "value_error.number.not_le"
    }
  ]
}

429 — rate limit exceeded

{ "detail": "Rate limit exceeded" }

Available metrics

Execution metrics

Metric	Response type	Description
`flow_runs`	`simple`	Total flow executions in the time range
`trigger_runs`	`simple`	Executions initiated by triggers
`manual_runs`	`simple`	Executions initiated manually (editor or API)
`agent_runs`	`simple`	Executions initiated by agents
`active_users`	`simple`	Distinct users who ran flows
`active_runs`	`simple`	Flows currently executing (live count)
`active_triggers`	`simple`	Currently enabled triggers
`errors`	`simple`	Number of failed runs
`average_run_time`	`simple`	Mean flow execution duration
`flow_runs_distribution`	`barchart`	Run count over time, split by source (manual, trigger, agent)
`flow_per_user`	`table`	Run count per user
`errors_over_time`	`barchart`	Failed runs over time
`run_time_over_time`	`barchart`	Execution duration over time (P25, P50, P90 percentiles)

Cost & token metrics

Metric	Response type	Description
`ai_models_total_cost`	`simple`	Estimated total LLM cost across all models
`ai_models_total_tokens`	`simple`	Total tokens consumed across all models
`average_cost_per_run`	`simple`	Mean estimated cost per flow execution
`tokens_cost`	`table`	Tokens and estimated cost grouped by LLM model
`tokens_cost_by_workflow`	`table`	Tokens and estimated cost per workflow
`tokens_cost_by_user`	`table`	Tokens and estimated cost per user
`model_tokens_total_cost`	`simple`	Estimated total cost (non-cached tokens only)
`ai_operations_per_tool`	`table`	AI Operation count grouped by tool type (flow, agent, KB)
`model_tokens_per_tool`	`table`	Token usage grouped by tool type
`ai_operations_per_user`	`table`	AI Operation count per user
`model_tokens_per_user`	`table`	Token usage per user

Costs are estimates based on publicly available model pricing. Cached LLM responses are excluded from cost calculations.

Currency of cost metrics

Model providers price their models in USD. The cost metrics above, and the conversation cost metrics below, convert these amounts into the billing currency of your organization (USD, EUR or GBP) at the European Central Bank rate for the start of the billing period. When no rate is available, amounts stay in USD and currency_note says so. All amounts in one response use the same currency.

A simple cost metric sets currency and puts the currency symbol in prefix.
In a table cost metric, each Cost cell is a cost object.
model_tokens_total_cost_per_workspace returns its bars in the same currency as model_tokens_total_cost.

Field	Description
`value`	The cost, in `currency`
`currency`	`"USD"`, `"EUR"` or `"GBP"`
`currency_note`	A short note about the currency, for display. For a USD organization it says that provider amounts are in USD. When the amounts could not be converted, they are in USD and the note gives the reason. Use `currency` to know the currency of the amounts, not this note.
`estimated_additional_cost`	The sum of the three estimated parts below
`estimated_in_progress_cost`	Estimated cost of calls that are still running
`estimated_interrupted_cost`	Estimated cost of calls that failed or were interrupted. It is not included in `value`.
`estimated_other_cost`	Estimated cost of finished calls whose provider did not report usage
`message`	A short explanation of how much of the cost is estimated

Do not assume that cost metrics are in USD. Read currency, or use prefix only for display.

Conversation metrics

Metric	Response type	Description
`conversations_started`	`simple`	Total conversations initiated
`messages_sent`	`simple`	Total messages sent (user + agent)
`messages_per_conversation`	`simple`	Average messages per conversation
`conversation_users`	`simple`	Distinct users who started conversations
`conversations_started_over_time`	`barchart`	Conversations started over time
`messages_sent_over_time`	`barchart`	Messages sent over time
`conversations_started_by_user`	`table`	Conversations started per user
`messages_sent_by_user`	`table`	Messages sent per user
`conversation_tokens_cost`	`table`	Token usage and cost per LLM model for conversations
`conversation_tokens_cost_by_user`	`table`	Conversation token usage and cost per user
`conversation_chat_costs_total`	`simple`	Estimated total cost of all conversation LLM calls

API usage metrics

Metric	Response type	Description
`api_calls_per_date`	`barchart`	API calls made per day/hour
`api_calls_per_endpoint`	`table`	API call count grouped by endpoint
`api_calls_log`	`table` (paginated)	Detailed log of recent API calls with endpoint, method, response code, and duration

Knowledge base metrics

Metric	Response type	Description
`kb_total_documents`	`simple`	Total documents across all knowledge bases
`kb_processed_successfully`	`simple`	Documents successfully ingested and indexed
`kb_failed_documents`	`simple`	Documents that failed ingestion
`kb_contributors`	`simple`	Distinct users who uploaded documents
`kb_documents_over_time`	`barchart`	Document ingestion count over time
`kb_documents_per_kb`	`table`	Document count per knowledge base
`kb_documents_by_user`	`table`	Document count per user
`kb_document_types`	`table`	Document count grouped by file type (PDF, Word, Excel, etc.)
`kb_user_activity`	`table`	Per-user breakdown of upload activity
`kb_overview`	`table`	Summary table across all knowledge bases

Examples

Total flow runs for January 2026

curl -X GET \
  "https://api.noxus.ai/v1/analytics/flow_runs?time_start=2026-01-01T00:00:00Z&time_end=2026-01-31T23:59:59Z" \
  -H "X-API-Key: your_api_key_here"

import requests

response = requests.get(
    "https://api.noxus.ai/v1/analytics/flow_runs",
    headers={"X-API-Key": "your_api_key_here"},
    params={
        "time_start": "2026-01-01T00:00:00Z",
        "time_end": "2026-01-31T23:59:59Z",
    },
)
data = response.json()
print(f"Total runs: {data['value']['value']}")

Response:

{
  "type": "simple",
  "value": {
    "value": 1842,
    "prefix": null,
    "suffix": " runs"
  }
}

LLM token usage by model (last 7 days)

curl -X GET \
  "https://api.noxus.ai/v1/analytics/tokens_cost?time_start=2026-02-20T00:00:00Z&time_end=2026-02-27T23:59:59Z" \
  -H "X-API-Key: your_api_key_here"

import requests

response = requests.get(
    "https://api.noxus.ai/v1/analytics/tokens_cost",
    headers={"X-API-Key": "your_api_key_here"},
    params={
        "time_start": "2026-02-20T00:00:00Z",
        "time_end": "2026-02-27T23:59:59Z",
    },
)
data = response.json()
for row in data["value"]["rows"]:
    print(row)

Response:

{
  "type": "table",
  "value": {
    "headings": ["Model", "Tokens", "Cost"],
    "rows": [
      {
        "Model": "gpt-4o",
        "Tokens": 250000,
        "Cost": {
          "value": 1.25,
          "currency": "EUR",
          "currency_note": null,
          "estimated_additional_cost": 0.05,
          "estimated_in_progress_cost": 0.05,
          "estimated_interrupted_cost": 0,
          "estimated_other_cost": 0,
          "message": "Estimates are about 4% of what the providers reported."
        }
      }
    ],
    "prefixes": null,
    "suffixes": null
  }
}

Paginated API call log

curl -X GET \
  "https://api.noxus.ai/v1/analytics/api_calls_log?time_start=2026-02-01T00:00:00Z&time_end=2026-02-27T23:59:59Z&page=1&page_size=20" \
  -H "X-API-Key: your_api_key_here"

Response:

{
  "type": "table",
  "value": {
    "headings": ["Endpoint", "Method", "Status", "Duration"],
    "items": [
      { "Endpoint": "/v1/workflows/{id}/runs", "Method": "POST", "Status": 200, "Duration": "142ms" }
    ],
    "total": 1560,
    "pages": 78,
    "size": 20,
    "page": 1
  }
}

Overview

Concepts

Flows

Agents

Knowledge Bases

Tables

Genie

Variables & Secrets

Tags

Tests

Analytics

Billing

Endpoint

Path parameter

Query parameters

Time range resolution

Rate limits

Response format

`simple` — a single scalar value

`barchart` — time-series data

`table` — tabular summary

`horizontal-barchart` — ranked distribution

`empty`

Error responses

Available metrics

Execution metrics

Cost & token metrics

Currency of cost metrics

Conversation metrics

API usage metrics

Knowledge base metrics

Examples

Total flow runs for January 2026

LLM token usage by model (last 7 days)

Paginated API call log

​Endpoint

​Path parameter

​Query parameters

​Time range resolution

​Rate limits

​Response format

​simple — a single scalar value

​barchart — time-series data

​table — tabular summary

​horizontal-barchart — ranked distribution

​empty

​Error responses

​Available metrics

​Execution metrics

​Cost & token metrics

​Currency of cost metrics

​Conversation metrics

​API usage metrics

​Knowledge base metrics

​Examples

​Total flow runs for January 2026

​LLM token usage by model (last 7 days)

​Paginated API call log

Endpoint

Path parameter

Query parameters

Time range resolution

Rate limits

Response format

`simple` — a single scalar value

`barchart` — time-series data

`table` — tabular summary

`horizontal-barchart` — ranked distribution

`empty`

Error responses

Available metrics

Execution metrics

Cost & token metrics

Currency of cost metrics

Conversation metrics

API usage metrics

Knowledge base metrics

Examples

Total flow runs for January 2026

LLM token usage by model (last 7 days)

Paginated API call log