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. `"$"`)
`suffix`	Optional string displayed after the value (e.g. `" runs"`)

`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": 0.25 }
    ],
    "prefixes": { "Cost": "$" },
    "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
`tokens_cost_by_node`	`table`	Tokens and estimated cost per node
`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.

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": 1.25 },
      { "Model": "claude-3-5-sonnet", "Tokens": 180000, "Cost": 0.54 }
    ],
    "prefixes": { "Cost": "$" },
    "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

Tests

Analytics

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

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

​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

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