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

# Analytics

> Track usage totals, rankings, and time series metrics.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

Analytics endpoints summarize how your workspace is being used across projects and users.

## Basic request and response

Start with totals to get a usage snapshot from `GET /api/v1/app/organization/analytics/totals`.

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/totals" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  {
    "projects_total": 12,
    "threads_total": 184,
    "interactions_total": 1420,
    "agent_flows_total": 36,
    "uploaded_artifacts_total": 87
  }
  ```
</Accordion>

## Active users ranking

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `start_date` | No | Start of the reporting window as Unix epoch milliseconds. |
  | Query | `end_date` | No | End of the reporting window as Unix epoch milliseconds. |
  | Query | `limit` | No | Maximum number of ranked users to return. Defaults to `5`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/ranking/active-users?start_date=1769990400000&end_date=1771804800000&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "account": {
        "id": "acct_6c8a1f3b2d4e5f7a",
        "state": "Active",
        "email": "sasha@example.com",
        "name": "Sasha Patel",
        "profile_picture": "https://{BASE_URL}/files/profile-picture.png",
        "provider": "Credentials",
        "roles": ["Workspace"],
        "created_at": "2026-02-08T14:12:45Z",
        "updated_at": "2026-02-08T14:12:45Z"
      },
      "interactions_created": 46,
      "agent_flows_created": 4
    }
  ]
  ```
</Accordion>

## Active projects ranking

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `start_date` | No | Start of the reporting window as Unix epoch milliseconds. |
  | Query | `end_date` | No | End of the reporting window as Unix epoch milliseconds. |
  | Query | `limit` | No | Maximum number of ranked projects to return. Defaults to `5`. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/ranking/active-projects?start_date=1769990400000&end_date=1771804800000&limit=5" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "project": {
        "id": "proj_7a5c3e1b9d2f4a6c",
        "name": "Customer Insights",
        "goal": "Summarize weekly support trends.",
        "visibility": "Public",
        "default_member_role": "Editor",
        "default_role_enabled": true,
        "project_context": "Support analytics for Q1.",
        "use_citations": true,
        "use_system_prompt": true,
        "members": [
          {
            "id": "{wsMemberId}",
            "role": "Owner",
            "account": {
              "id": "acct_6c8a1f3b2d4e5f7a",
              "state": "Active",
              "email": "sasha@example.com",
              "name": "Sasha Patel",
              "provider": "Credentials",
              "roles": [
                "Workspace"
              ],
              "created_at": "2026-02-08T14:12:45Z",
              "updated_at": "2026-02-08T14:12:45Z"
            },
            "is_project_member": true
          }
        ],
        "is_pinned": false
      },
      "interactions_created": 112,
      "agent_flows_created": 12
    }
  ]
  ```
</Accordion>

The nested project follows the [Project response model](/en/v1.58/developer-manual/build-with-zylon/workspace-api/projects/project#project-response-fields), including member accounts. Nullable project fields can be omitted.

## Time series

Both date bounds are required. Results are weekly counts at seven-day intervals starting on the requested start date.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `start_date` | Yes | Start of the reporting window as Unix epoch milliseconds. |
  | Query | `end_date` | Yes | End of the reporting window as Unix epoch milliseconds. |
  | Query | `type` | Yes | `Thread`, `Interactions`, `artifact_agent_flow`, or `artifact_document`; case-insensitive. |
</Accordion>

```bash theme={null}
curl "https://{BASE_URL}/api/v1/app/organization/analytics/timeseries?start_date=1769990400000&end_date=1771804800000&type=interactions" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"
```

<Accordion title="Example response">
  ```json theme={null}
  [
    { "date": "2026-02-02", "value": 18 },
    { "date": "2026-02-09", "value": 25 },
    { "date": "2026-02-16", "value": 21 },
    { "date": "2026-02-23", "value": 19 }
  ]
  ```
</Accordion>

## Errors and edge cases

* **400**: invalid date range or type.
* **403**: insufficient permissions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.