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

# Analytics API v2

> Next-generation analytics API for querying consumption, active users, agent output, and tool calls with Bearer-token authentication, grouping, and pagination.

<Warning>
  The v2 APIs are in **alpha** and subject to change at any time.
</Warning>

## Overview

Analytics API v2 is the next generation of the Devin Desktop Analytics API. It exposes consumption
analytics (credits and ACUs), active users, agent output (accepted lines of code), and agent tool calls through clean REST endpoints with
query-parameter filtering, flexible grouping, and cursor-based pagination.

<Note>
  v2 endpoints are currently served under the **`/api/v2alpha`** prefix while the API surface is
  finalized. The base URL is `https://server.codeium.com`.
</Note>

## What's new in v2

The biggest change from [v1](/desktop/accounts/api-reference/analytics-api-introduction) is **authentication**.

| | v1 Analytics API | v2 Analytics API |
| - | - | - |
| Transport | `POST` with a JSON request body | `GET` with query parameters |
| Auth | `service_key` field **in the request body** | **`Authorization: Bearer <token>` header** |
| Credentials | Windsurf service key | Windsurf service key **or Devin service user API key** |
| Permission | Varies per endpoint | **Analytics Read** (Windsurf) / **Use Local Analytics API** (Devin) |
| Pagination | None | Cursor-based (`next_page_cursor` / `page_cursor`) |

## Authentication

v2 uses **Bearer token** authentication. Pass your credential in the `Authorization` header instead
of in the request body:

```
Authorization: Bearer <your_token>
```

Two kinds of credential are accepted: a **Devin service user API key** (recommended — the same
`cog_` key you use for the [Devin API](/api-reference/authentication)) or a **Windsurf service key**.

### Devin service user API keys

If you already manage Devin service users, you do not need separate Windsurf credentials:

1. Provision a service user under **Settings > Devin API** (**Service users** tab) for an
   organization, or **Enterprise settings > Devin API** (**Service users** tab) for the enterprise
2. Assign it a [custom role](/enterprise/security-access/custom-roles) that includes the
   **Use Local Analytics API** permission (the built-in admin role already includes it)
3. Copy the API key shown after provisioning — it starts with `cog_`
4. Use that key as the Bearer token

```bash theme={null}
curl "https://server.codeium.com/api/v2alpha/analytics/consumption?start_date=2026-08-01&end_date=2026-08-07&product=agent" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

Results cover the whole Devin account the service user belongs to, and `metadata.team_id` is the
account's Devin team identifier (`devin-team$<account_id>`).

<Note>
  The `group_id` filter is a Windsurf teams concept and is not supported with Devin credentials —
  requests that combine the two return `400 Bad Request`.
</Note>

### Windsurf service keys

1. Navigate to your [team settings page](https://windsurf.com/team/settings)
2. Go to the "Service Keys" section
3. Create a new service key with the **Analytics Read** permission
4. Use the key as a Bearer token in the `Authorization` header

Group-scoped service keys are supported — when a key is scoped to a group, results are automatically
limited to that group.

<Warning>Keep these credentials secure and never expose them in client-side code or public repositories.</Warning>

## Available endpoints

| Endpoint | Description |
| - | - |
| [Get Consumption](/desktop/accounts/api-reference/get-consumption) (`GET /api/v2alpha/analytics/consumption`) | Query credit or ACU consumption with filtering, grouping, granularity, and pagination |
| [Get Active Users](/desktop/accounts/api-reference/get-active-users) (`GET /api/v2alpha/analytics/active-users`) | Count distinct active users, optionally by day/month or per user |
| [Get Output](/desktop/accounts/api-reference/get-output) (`GET /api/v2alpha/analytics/output?metric=loc_inserted,loc_deleted`) | Lines of code inserted and deleted by the agent and accepted in Devin Desktop or the Devin CLI, with the same filters and grouping plus `session` and `source` |
| [Get Tools](/desktop/accounts/api-reference/get-tools) (`GET /api/v2alpha/analytics/tools?metric=calls`) | Number of tool calls the agent made in Devin Desktop or the Devin CLI, grouped by tool category (such as `SEARCH_WEB`), user, model, IDE, or OS |

## Billing strategy

Consumption responses adapt to your team's billing strategy, reported in `metadata.billing_strategy` (output, tools, and active-user responses are unaffected):

* **`CREDITS`** — rows include `prompt_credits` and `flex_credits`
* **`ACU`** — rows include `billed_acus`

The `message_count` (billing events) and `user_message_count` (user-sent messages, `null` for usage before 2026-04-11) fields are always returned regardless of strategy.

## Pagination

List responses are paginated. When more data is available, the response includes a
`pagination.next_page_cursor`; pass it back as the `page_cursor` query parameter to fetch the next
page. Cursors expire after 24 hours.

## Rate limits

<Warning>
  These endpoints are **not** intended for real-time usage monitoring. Data is hourly-aggregated and
  the rate limit is low (10 requests per hour per team). Use them for periodic reporting and bulk
  export, not live dashboards or per-request tracking.
</Warning>

v2 endpoints are rate-limited to **10 requests per hour per team**. Exceeding the limit returns
`429 Too Many Requests` with a `Retry-After` header.

Paginating an earlier query (following a `next_page_cursor`) does **not** count against the rate
limit — only the initial query for each report does. The low limit reflects that these endpoints are
for periodic reporting, not real-time monitoring.


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