> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API

> Query workspace metrics programmatically via the REST 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.

<Tip>
  For interactive endpoint documentation with request/response examples, see the [API reference](/api-reference/introduction).
</Tip>

Authentication follows the same API key mechanism used across all v1 endpoints — refer to the [API reference](/api-reference/introduction) for details.

***

## Endpoint

```
GET /v1/analytics/{metric}
```

### Path parameter

| Parameter | Type   | Description                                                                                         |
| --------- | ------ | --------------------------------------------------------------------------------------------------- |
| `metric`  | string | The analytics metric to retrieve. See [Available Metrics](#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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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**

```json theme={null}
{ "detail": "time_start must be before time_end" }
```

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

```json theme={null}
{
  "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**

```json theme={null}
{ "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                                      |

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

### 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "type": "simple",
  "value": {
    "value": 1842,
    "prefix": null,
    "suffix": " runs"
  }
}
```

***

### LLM token usage by model (last 7 days)

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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
  }
}
```