---
title: "Get spend per agent"
method: GET
path: "/v1/projects/{project_id}/budgets/agent-ranking"
tags: ["budgets"]
---

# Get spend per agent

`GET /v1/projects/{project_id}/budgets/agent-ranking`

## Request

- Base URL: `https://api.connic.co`
- URL: `https://api.connic.co/v1/projects/{project_id}/budgets/agent-ranking`
- Auth: HTTP bearer

Token usage and native-currency cost by agent for the chosen month (default: current), sorted by name. Each row includes an exact per-currency cost breakdown, agent and judge token usage, and run count. Covers every environment the caller can access; pass `environment_id` to limit to one. `group_by=model` ranks models; `group_by=context.<key>` ranks run context values such as `context.customer_id`, with `context_value: null` for runs that do not set it.

Required permission: `budgets.view`.

## Path parameters

- `project_id` string, uuid, required

## Query parameters

- `month` string, nullable: Month in YYYY-MM format
- `environment_id` string, uuid, nullable: Restrict to one environment UUID
- `start_date` string, date-time, nullable: Exact range start; applies only together with `end_date` and replaces the month bounds
- `end_date` string, date-time, nullable: Exact range end (exclusive); applies only together with `start_date`
- `tz_offset` integer, nullable: UTC offset in minutes, with the sign inverted (-120 for UTC+2, 300 for UTC-5). Days are grouped in this timezone; defaults to UTC.
- `group_by` string: Group spend by 'agent', 'model', or a run context path such as 'context.customer_id'
- `convert_costs_to` 'EUR' | 'USD', nullable: Convert token costs to EUR or USD at the daily ECB reference rate of each model call

## Response `200`

Successful Response

- PublicAgentRankingResponse
  - `month` string, required: Month in `YYYY-MM` format.
  - `currencies` string[], required: Currency codes with a nonzero cost in the results.
  - `agents` union[], required: One row per agent, model or context value, depending on `group_by`, sorted by name.
    - union
      - PublicAgentRankingItemResponse
        - `token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set.
          - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included.
          - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code.
          - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced.
            - `complete` boolean, required: True when every model call could be priced.
            - `call_count` integer, required: Model calls covered by the report.
            - `priced_call_count` integer, required: Calls included in the cost amounts.
            - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts.
            - `unpriced_models` string[], required: Models of the unpriced calls.
          - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set.
          - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set.
        - `agent_token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set.
          - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included.
          - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code.
          - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced.
            - `complete` boolean, required: True when every model call could be priced.
            - `call_count` integer, required: Model calls covered by the report.
            - `priced_call_count` integer, required: Calls included in the cost amounts.
            - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts.
            - `unpriced_models` string[], required: Models of the unpriced calls.
          - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set.
          - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set.
        - `run_count` integer, required: Runs started in the period for this group.
        - `agent_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `judge_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `total_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `agent_token_usage_by_currency` object, required: Agent tokens from priced calls, keyed by the currency they were priced in.
        - `judge_token_usage_by_currency` object, required: Judge tokens from priced calls, keyed by the currency they were priced in.
        - `total_token_usage_by_currency` object, required: Agent and judge tokens from priced calls, keyed by the currency they were priced in.
        - `agent_name` string, required: Agent the row belongs to (`group_by=agent`).
      - PublicModelRankingItemResponse
        - `token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set.
          - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included.
          - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code.
          - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced.
            - `complete` boolean, required: True when every model call could be priced.
            - `call_count` integer, required: Model calls covered by the report.
            - `priced_call_count` integer, required: Calls included in the cost amounts.
            - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts.
            - `unpriced_models` string[], required: Models of the unpriced calls.
          - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set.
          - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set.
        - `agent_token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set.
          - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included.
          - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code.
          - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced.
            - `complete` boolean, required: True when every model call could be priced.
            - `call_count` integer, required: Model calls covered by the report.
            - `priced_call_count` integer, required: Calls included in the cost amounts.
            - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts.
            - `unpriced_models` string[], required: Models of the unpriced calls.
          - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set.
          - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set.
        - `run_count` integer, required: Runs started in the period for this group.
        - `agent_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `judge_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `total_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `agent_token_usage_by_currency` object, required: Agent tokens from priced calls, keyed by the currency they were priced in.
        - `judge_token_usage_by_currency` object, required: Judge tokens from priced calls, keyed by the currency they were priced in.
        - `total_token_usage_by_currency` object, required: Agent and judge tokens from priced calls, keyed by the currency they were priced in.
        - `model_name` string, required: Model the row belongs to (`group_by=model`).
      - PublicContextRankingItemResponse
        - `token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set.
          - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included.
          - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code.
          - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced.
            - `complete` boolean, required: True when every model call could be priced.
            - `call_count` integer, required: Model calls covered by the report.
            - `priced_call_count` integer, required: Calls included in the cost amounts.
            - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts.
            - `unpriced_models` string[], required: Models of the unpriced calls.
          - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set.
          - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set.
        - `agent_token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set.
          - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included.
          - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code.
          - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced.
            - `complete` boolean, required: True when every model call could be priced.
            - `call_count` integer, required: Model calls covered by the report.
            - `priced_call_count` integer, required: Calls included in the cost amounts.
            - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts.
            - `unpriced_models` string[], required: Models of the unpriced calls.
          - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set.
          - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set.
        - `run_count` integer, required: Runs started in the period for this group.
        - `agent_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `judge_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `total_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls.
          - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens.
          - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens.
          - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache.
          - `thinking_tokens` integer, required: Reasoning tokens the model generated.
          - `total_tokens` integer, required: Input, output and thinking tokens combined.
          - `audio_input_tokens` integer: Part of `input_tokens` that was audio.
          - `audio_output_tokens` integer: Part of `output_tokens` that was audio.
          - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio.
          - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio.
          - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low.
        - `agent_token_usage_by_currency` object, required: Agent tokens from priced calls, keyed by the currency they were priced in.
        - `judge_token_usage_by_currency` object, required: Judge tokens from priced calls, keyed by the currency they were priced in.
        - `total_token_usage_by_currency` object, required: Agent and judge tokens from priced calls, keyed by the currency they were priced in.
        - `context_value` string, nullable, required: Run context value at the `group_by` path. Null for runs that do not set it.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required permission or access to the environment.
- `422`: Validation Error
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/connic/apis/connic-api.md) · [All operations](https://skmtc.dev/connic/apis/connic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/connic/apis/connic-api/revisions/482932da5fbe?raw)