> ## 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 data with Bearer-token authentication, flexible grouping, and cursor-based 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) through clean REST endpoints with query-parameter filtering, flexible
grouping, cursor-based pagination, and response caching.

<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 <service_key>` header**  |
| Permission | Varies per endpoint                         | **Analytics Read**                                |
| Pagination | None                                        | Cursor-based (`next_page_cursor` / `page_cursor`) |
| Caching    | None                                        | `ETag` + `If-None-Match` (`304 Not Modified`)     |

## Authentication

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

```
Authorization: Bearer <your_service_key>
```

The service key must have the **Analytics Read** permission.

### Creating a service key

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

<Warning>Keep your service keys secure and never expose them in client-side code or public repositories.</Warning>

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

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

## Billing strategy

Responses adapt to your team's billing strategy, reported in `metadata.billing_strategy`:

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

The `message_count` field is 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.

## Caching

Responses include an `ETag` header. Send it back in the `If-None-Match` header on subsequent requests
to receive a `304 Not Modified` when the data is unchanged.

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