Skip to main content
GET
/
api
/
v2alpha
/
analytics
/
consumption
Get consumption analytics
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/consumption \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "timestamp": "2026-01-15",
      "user_id": "user_abc123",
      "user_email": "alice@example.com",
      "consumption": {
        "prompt_credits": 1250,
        "flex_credits": 340,
        "message_count": 87
      }
    },
    {
      "timestamp": "2026-01-15",
      "user_id": "user_def456",
      "user_email": "bob@example.com",
      "consumption": {
        "prompt_credits": 980,
        "flex_credits": 150,
        "message_count": 52
      }
    }
  ],
  "pagination": {
    "next_page_cursor": null
  },
  "metadata": {
    "billing_strategy": "CREDITS",
    "data_freshness": "2026-01-16T03:00:00Z",
    "query_time_ms": 1423,
    "team_id": "team_abc123"
  }
}
This is a v2 endpoint that uses Bearer token authentication and query parameters, unlike the v1 Analytics API which uses service keys in the request body. See Authentication below.
This endpoint is not intended for real-time usage monitoring. Data is hourly-aggregated and the rate limit is low (10 requests per hour per team). Use it for periodic reporting and bulk export.

​
Authentication

This endpoint uses Bearer token authentication. Include your service key in the Authorization header: 
Authorization: Bearer <your_service_key>
The service key must have the Analytics Read permission. Create one in your team settings under “Service Keys”.

​
Billing Strategy

The response shape depends on your team’s billing strategy:
StrategyPopulated fieldsDescription
CREDITSprompt_credits, flex_creditsStandard Enterprise SaaS teams
ACUbilled_acusTeams billed by Agent Compute Units
The message_count field (inside consumption) is always populated regardless of billing strategy.

​
Grouping and Granularity

Use granularity and group_by to control the shape of returned data:
  • No granularity or grouping — returns a single aggregated row for the entire date range
  • granularity=daily — each row includes a timestamp in YYYY-MM-DD format
  • granularity=monthly — each row includes a timestamp in YYYY-MM format
  • group_by=user — each row includes a user_id and user_email
  • group_by=user,model_uid — each row includes user_id, user_email, and model_uid
  • group_by=ide — each row includes an ide

​
Pagination

Results are paginated with a default page size of 1,000 rows (max 10,000). When more results are available, the response includes a next_page_cursor in the pagination object. Pass it as the page_cursor query parameter to fetch the next page. Page cursors expire after 24 hours. A follow-up page request does not count as a new query against your rate limit.

​
Caching

Responses include an ETag header. To avoid redundant data transfer, include the If-None-Match header with the previous ETag value — the server will return 304 Not Modified if the data has not changed.

​
Rate Limits

This endpoint is rate-limited to 10 requests per hour per team. If you exceed this limit, the server returns 429 Too Many Requests with a Retry-After header. Paginating an earlier query (following a next_page_cursor) does not count against this limit — only the initial query for each report does. The low limit reflects that this endpoint is for periodic reporting, not real-time usage monitoring.

Authorizations

​
Authorization
string
header
required

A service key with Analytics Read permission, passed as a Bearer token in the Authorization header.

Create a service key in your team settings under the "Service Keys" section.

Headers

​
If-None-Match
string

ETag value from a previous response. If the data has not changed, the server returns 304 Not Modified.

Query Parameters

​
start_date
string<date>
required

Start of the date range (inclusive) in YYYY-MM-DD format.

​
end_date
string<date>
required

End of the date range (inclusive) in YYYY-MM-DD format. The range must not exceed 90 days.

​
product
enum<string>
required

Product to query consumption for.

Available options:
agent
​
granularity
enum<string>

Time granularity for grouping results. When specified, each row includes a timestamp field. If omitted, results are aggregated across the entire date range.

Available options:
daily,
monthly
​
group_by
string

Comma-separated list of dimensions to group results by. Supported dimensions:

  • user — includes user_id and user_email in each row
  • model_uid — includes model_uid in each row
  • ide — includes ide in each row
​
models
string

Comma-separated list of model UIDs to filter results to.

​
group_id
string

Filter results to users in a specific group. The service key must have access to this group.

​
user_id
string

Filter results to a specific user (auth UID).

​
page_size
integer
default:1000

Maximum number of rows to return per page.

Required range: 1 <= x <= 10000
​
page_cursor
string

Opaque cursor from a previous response's pagination.next_page_cursor to fetch the next page.

Response

Consumption data returned successfully.

​
data
object[]
required

Array of consumption data rows.

​
pagination
object
required
​
metadata
object
required