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

# Get Consumption

> Query credit, ACU, or token consumption analytics with flexible filtering, grouping, and pagination.

<Note>
  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](#authentication) below.
</Note>

<Warning>
  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.
</Warning>

## Authentication

This endpoint uses **Bearer token** authentication. Include your token in the `Authorization` header:

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

Use either a Devin service user API key with the **Use Local Analytics API** permission or a Windsurf
service key with the **Analytics Read** permission. See
[Authentication](/desktop/accounts/api-reference/analytics-v2-introduction#authentication) for how to
create each one.

## Billing Strategy

The response shape depends on your team's billing strategy:

| Strategy | Populated fields | Description |
| - | - | - |
| `ACU` | `billed_acus` | Standard Devin enterprise billing, shared with Devin Cloud |
| `CREDITS` | `prompt_credits`, `flex_credits` | Legacy Windsurf enterprises |
| `DOLLARS` | `tokens` | Select teams with granular token billing enabled (see [Token Usage](#token-usage)) |

The `message_count` and `user_message_count` fields (inside `consumption`) are returned regardless of
billing strategy. `user_message_count` counts only messages a user sent to the agent, from any client (Devin
Desktop, the JetBrains plugin, or the CLI); it is the same number as "messages sent" in the analytics UI.
`message_count` counts every billing event, including the follow-on model and tool requests within each turn. `user_message_count` is `null` for rows with no
user-message attribution (usage before 2026-04-11).

## Token Usage

For teams with granular token billing enabled (`DOLLARS`), each row also includes a `tokens` object with the
token counts for the row. It uses the same `granularity` and `group_by` as `consumption`, so grouping by
`session` gives per-session token totals.

| Field | Description |
| - | - |
| `input_tokens` | Uncached input tokens. Excludes cache reads and writes. |
| `cache_read_tokens` | Input tokens read from the model provider's prompt cache. |
| `cache_write_tokens` | Input tokens written to the model provider's prompt cache. |
| `output_tokens` | Output tokens. |

Total input tokens are `input_tokens + cache_read_tokens + cache_write_tokens`. Usage from before token counts
were recorded for this endpoint counts as `0`. Teams not billed per token, and
requests authenticated with a Windsurf service key, don't receive the `tokens` object; Windsurf service-key
requests report the team's `CREDITS` or `ACU` strategy and fields instead of `DOLLARS`.

For these organizations, `metadata.billing_strategy` is `DOLLARS` and `consumption` contains only `message_count` and `user_message_count`: credit and ACU
fields (`prompt_credits`, `flex_credits`, `billed_acus`) are omitted.

## 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=session`** — each row includes a `session_id`
* **`group_by=user,model_uid`** — each row includes `user_id`, `user_email`, and `model_uid`
* **`group_by=ide`** — each row includes an `ide`
* **`group_by=ide,ide_version`** — each row includes `ide` and `ide_version` (grouping by `ide_version` requires `ide` to also be included)
* **`group_by=os`** — each row includes an `os`, such as `darwin` (macOS), `windows`, or `linux`

<Note>
  To measure what the agent produced rather than what it consumed, use
  [Get Output](/desktop/accounts/api-reference/get-output) (`metric=loc_inserted,loc_deleted`), which returns
  accepted lines of code with the same filters and grouping dimensions.
</Note>

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

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


## OpenAPI

````yaml desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/consumption
openapi: 3.1.0
info:
  title: Devin Desktop Analytics API v2
  version: 2.0.0
  description: >
    The Analytics API v2 provides credit and ACU consumption, active-user, agent
    output

    (accepted lines of code), and agent tool-call analytics for enterprise
    teams. Data is sourced from

    hourly aggregates and supports flexible filtering, grouping, and
    cursor-based pagination.
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/consumption:
    get:
      summary: Get consumption analytics
      description: >
        Query credit or ACU consumption data for the authenticated team. Results
        are sourced from

        hourly-aggregated billing events and can be filtered by date range,
        product, model, and group.


        The response shape depends on the team's billing strategy:

        - **Credits-based** teams receive `prompt_credits` and `flex_credits` in
        each row.

        - **ACU-based** teams receive `billed_acus` in each row.


        These endpoints are designed for periodic reporting and bulk export.
        They are **not** intended for real-time usage monitoring: data is
        hourly-aggregated and the rate limit is low (10 requests per hour per
        team).
      operationId: getConsumption
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start of the date range (inclusive) in `YYYY-MM-DD` format.
          example: '2026-06-01'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: >-
            End of the date range (inclusive) in `YYYY-MM-DD` format. The range
            must not exceed 90 days.
          example: '2026-06-30'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: Product to query consumption for.
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: >
            Time granularity for grouping results. When specified, each row
            includes a `timestamp` field.

            If omitted, results are aggregated across the entire date range.
        - name: group_by
          in: query
          required: false
          schema:
            type: string
          description: >
            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

            - `ide_version` — includes `ide_version` in each row; requires `ide`
            to also be included

            - `os` — includes `os` in each row
          example: user,model_uid
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of model UIDs to filter results to.
          example: claude-4-sonnet,gpt-4.1
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filter results to users in a specific group. The service key must
            have access to this group.
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: Filter results to a specific user (auth UID).
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: Maximum number of rows to return per page.
        - name: page_cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque cursor from a previous response's
            `pagination.next_page_cursor` to fetch the next page.
      responses:
        '200':
          description: Consumption data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionResponse'
              examples:
                credits:
                  summary: Credits-based team with daily granularity
                  value:
                    data:
                      - timestamp: '2026-06-15'
                        user_id: user_abc123
                        user_email: alice@example.com
                        consumption:
                          prompt_credits: 1250
                          flex_credits: 340
                          message_count: 87
                          user_message_count: 31
                      - timestamp: '2026-06-15'
                        user_id: user_def456
                        user_email: bob@example.com
                        consumption:
                          prompt_credits: 980
                          flex_credits: 150
                          message_count: 52
                          user_message_count: 19
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: CREDITS
                      data_freshness: '2026-06-16T03:00:00Z'
                      query_time_ms: 1423
                      team_id: team_abc123
                os:
                  summary: Credits-based team grouped by operating system
                  value:
                    data:
                      - os: darwin
                        consumption:
                          prompt_credits: 8400
                          flex_credits: 1200
                          message_count: 613
                          user_message_count: 214
                      - os: windows
                        consumption:
                          prompt_credits: 5100
                          flex_credits: 730
                          message_count: 402
                          user_message_count: 143
                      - os: linux
                        consumption:
                          prompt_credits: 1900
                          flex_credits: 260
                          message_count: 155
                          user_message_count: 56
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: CREDITS
                      data_freshness: '2026-06-16T03:00:00Z'
                      query_time_ms: 1105
                      team_id: team_abc123
                tokens:
                  summary: Team billed per token, grouped by session
                  value:
                    data:
                      - session_id: 8f14e45f-ceea-467f-a0e6-2a3b4c5d6e7f
                        consumption:
                          message_count: 64
                          user_message_count: 9
                        tokens:
                          input_tokens: 182340
                          cache_read_tokens: 4129870
                          cache_write_tokens: 301552
                          output_tokens: 48211
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: DOLLARS
                      data_freshness: '2026-06-16T03:00:00Z'
                      query_time_ms: 1310
                      team_id: team_def456
                acu:
                  summary: ACU-based team
                  value:
                    data:
                      - consumption:
                          billed_acus: 42.75
                          message_count: 310
                          user_message_count: 108
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: ACU
                      data_freshness: '2026-06-16T03:00:00Z'
                      query_time_ms: 892
                      team_id: team_def456
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_param:
                  value:
                    error: start_date is required
                date_range:
                  value:
                    error: date range must not exceed 90 days
                bad_product:
                  value:
                    error: 'unsupported product: foo (supported: agent)'
        '401':
          description: Authentication failed or insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_auth:
                  value:
                    error: missing Authorization header
                invalid_key:
                  value:
                    error: invalid service key
                insufficient_permissions:
                  value:
                    error: insufficient permissions
        '403':
          description: >-
            The supplied page cursor does not belong to the authenticated team
            or requested group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                cursor_team_mismatch:
                  value:
                    error: page cursor does not belong to this team
        '405':
          description: HTTP method not allowed (only `GET` is supported).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Rate limit exceeded (10 requests per hour per team). Paginating an
            earlier query does not count against this limit.
          headers:
            Retry-After:
              schema:
                type: string
              description: Suggested wait time before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: rate limit exceeded
        '503':
          description: >-
            Analytics service is not available (e.g., in self-hosted
            deployments).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ConsumptionResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionRow'
          description: Array of consumption data rows.
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: >
                Opaque cursor for fetching the next page of results. Pass this
                value as the `page_cursor`

                query parameter in a follow-up request. `null` when there are no
                more pages.

                Page cursors expire after 24 hours.
        metadata:
          type: object
          properties:
            billing_strategy:
              type: string
              enum:
                - ACU
                - CREDITS
                - DOLLARS
              description: >
                The billing strategy for the authenticated team. Determines
                which fields in `consumption` are populated:

                - `ACU` — standard Devin enterprise billing, shared with Devin
                Cloud: `billed_acus`

                - `CREDITS` — legacy Windsurf enterprises: `prompt_credits` and
                `flex_credits`

                - `DOLLARS` — select teams with granular token billing enabled:
                no credit or ACU fields; each row includes `tokens` (not
                returned to Windsurf service-key requests, which get the team's
                `CREDITS` or `ACU` strategy)
            data_freshness:
              type: string
              format: date-time
              description: >-
                Timestamp indicating when the underlying data was last refreshed
                (truncated to the hour).
            query_time_ms:
              type: integer
              format: int64
              description: Server-side query execution time in milliseconds.
            team_id:
              type: string
              description: The team ID resolved from the authenticated service key.
            group_id:
              type: string
              description: >-
                The group ID the results were scoped to. Only present when
                `group_id` was supplied.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
    ConsumptionRow:
      type: object
      required:
        - consumption
      properties:
        timestamp:
          type: string
          description: >
            Time bucket for the row. Format depends on `granularity`:
            `YYYY-MM-DD` for daily, `YYYY-MM` for monthly.

            Only present when `granularity` is specified.
          examples:
            - '2026-05-01'
            - 2026-05
        user_id:
          type: string
          description: >-
            User identifier (auth UID). Only present when `group_by` includes
            `user`.
        user_email:
          type: string
          description: User's email address. Only present when `group_by` includes `user`.
          examples:
            - alice@example.com
        session_id:
          type: string
          description: >-
            Devin Desktop conversation or Devin CLI session identifier. Only
            present when `group_by` includes `session`.
        model_uid:
          type: string
          description: Model identifier. Only present when `group_by` includes `model_uid`.
          examples:
            - claude-4-sonnet
        ide:
          type: string
          description: IDE name. Only present when `group_by` includes `ide`.
          examples:
            - windsurf
            - jetbrains
        ide_version:
          type: string
          description: >-
            IDE version. Only present when `group_by` includes `ide_version`
            (which additionally requires `ide`).
          examples:
            - 1.0.0
        os:
          type: string
          description: >-
            Operating system the request came from. Only present when `group_by`
            includes `os`.
          examples:
            - darwin
            - windows
            - linux
        consumption:
          $ref: '#/components/schemas/Consumption'
        tokens:
          $ref: '#/components/schemas/Tokens'
          description: >
            Token counts for the row. Only present for organizations billed per
            token. Usage from before token

            counts were recorded for this endpoint counts as `0`.
    Consumption:
      type: object
      description: >-
        Usage metrics for the row. Fields are populated based on the team's
        billing strategy.
      properties:
        prompt_credits:
          type: integer
          format: int64
          description: >-
            Prompt credits consumed (credits-based billing only). Omitted for
            organizations billed per token.
        flex_credits:
          type: integer
          format: int64
          description: >-
            Flex credits consumed (credits-based billing only). Omitted for
            organizations billed per token.
        billed_acus:
          type: number
          format: double
          description: >-
            Billed ACUs consumed (ACU-based billing only). Omitted for
            organizations billed per token.
        message_count:
          type: integer
          format: int64
          description: >
            Number of billing events in this row. Each user message and each
            follow-on model or tool request

            within a turn is a separate billing event, so this is typically
            several times `user_message_count`.

            Always populated regardless of billing strategy.
        user_message_count:
          type:
            - integer
            - 'null'
          format: int64
          description: >
            Number of user-authored messages in this row: messages a user sent
            to the agent from any client (Devin

            Desktop, the JetBrains plugin, or the CLI), matching the "messages
            sent" counter shown in the analytics UI. Returned regardless of
            billing strategy.

            `null` when no user-message attribution exists for the row, which is
            the case for usage before

            2026-04-11; for ranges spanning that date only the later usage is
            counted.
    Tokens:
      type: object
      description: >
        Token counts for the row. Only returned for teams with granular token
        billing enabled (`DOLLARS`).

        Grouped by the same `granularity` and `group_by` as `consumption`. Total
        input tokens are

        `input_tokens + cache_read_tokens + cache_write_tokens`.
      properties:
        input_tokens:
          type: integer
          format: int64
          description: Uncached input tokens. Excludes cache reads and writes.
        cache_read_tokens:
          type: integer
          format: int64
          description: Input tokens read from the model provider's prompt cache.
        cache_write_tokens:
          type: integer
          format: int64
          description: Input tokens written to the model provider's prompt cache.
        output_tokens:
          type: integer
          format: int64
          description: Output tokens.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        A service key with **Analytics Read** permission, passed as a Bearer
        token in the `Authorization` header.


        Create a service key in your [team
        settings](https://windsurf.com/team/settings) under the "Service Keys"
        section.

````

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