Usage and Cost Analytics API

Usage and Cost Analytics API предоставляет исторические данные об использовании токенов и затратах вашей организации в разбивке по выбранным вами измерениям, таким как модель, рабочее пространство, ключ API или пользователь либо сервисный аккаунт, стоящий за каждым запросом. Для организаций Claude Console эти данные аналогичны тем, что отображаются на страницах Usage и Cost в Claude Console.

API имеет две конечные точки:

• GET /v1/organizations/analytics/usage возвращает количество токенов и количество запросов.
• GET /v1/organizations/analytics/cost возвращает затраты в долларах США.

Usage and Cost Analytics API находится в стадии бета-тестирования. В каждом запросе отправляйте anthropic-beta: analytics-usage-cost-2026-08-24 в качестве заголовка, а также заголовок anthropic-version. SDK и CLI ant отправляют оба заголовка за вас и загружают оставшиеся страницы по мере чтения результатов, поэтому limit задаёт только размер страницы.

Используйте этот API, чтобы:

• Распределять расходы: разбивать затраты и использование токенов по рабочим пространствам, ключам API, моделям, уровням обслуживания или по идентичности, выполнившей каждый запрос.
• Находить крупнейших потребителей: ранжировать результаты по токенам, запросам или затратам, чтобы отвечать на такие вопросы, как «какие ключи API тратят больше всего в этом месяце?»
• Строить временные ряды: разбивать результаты на ежедневные, ежечасные или поминутные интервалы для дашбордов и финансовых отчётов.
• Интегрироваться один раз: одни и те же конечные точки, параметры и поля ответа обслуживают организации Claude Console и Claude Enterprise.

Быстрый старт

Получите ежедневное использование токенов за первую неделю сентября, по одной строке для каждой модели и дня:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Ответ содержит по одной строке для каждой модели и дня, в которых было использование, начиная с наибольшего total_tokens. В этом примере показана одна строка:

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

Структура результатов

• Каждая строка состоит из трёх частей: starting_at и ending_at задают период, который охватывает строка, group содержит все измерения, а usage (или cost на конечной точке затрат) содержит метрики.
• Измерения равны null, если по ним нет группировки: измерение в group имеет значение null, если вы не указали его в group_by[]. Сгруппированное измерение также имеет значение null в строках, где для него нет значения, например model для использования выполнения кода. group_by[] принимает до пяти измерений.
• Одна строка для каждой комбинации: каждая строка — это одна комбинация сгруппированных измерений, и каждая комбинация, для которой есть использование или затраты, встречается ровно один раз на всех страницах запроса. Без group_by[] и без time_bucket_width ответ состоит из одной строки с итогом за весь диапазон.
• Временные интервалы необязательны: задайте time_bucket_width равным 1m, 1h или 1d, чтобы разбить каждую комбинацию по интервалам UTC; тогда starting_at и ending_at каждой строки являются границами её интервала. Интервалы без использования или затрат не порождают строк.
• По умолчанию строки ранжируются: строки упорядочиваются по метрике order_by за весь диапазон, по умолчанию от наибольшей (order=asc меняет порядок на обратный). Чтобы построить временной ряд, задайте time_bucket_width и order_by=time. Тогда строки возвращаются интервал за интервалом, по умолчанию начиная с самого нового интервала (order=asc ставит первым самый старый), а внутри каждого интервала первыми идут наибольшие строки. Заполните пустые интервалы нулями.
• Фильтры работают вместе с группировкой: для большинства измерений, по которым можно группировать, есть соответствующий списочный фильтр в скобочной нотации, например models[]=claude-opus-5-5. Повторите параметр, чтобы передать несколько значений, до 100. Несколько значений одного фильтра объединяются через OR, а разные фильтры — через AND. Фильтры и group_by[] независимы: вы можете фильтровать по любому измерению с группировкой по нему или без неё, и наоборот.

Такие измерения, как model и actor, применимы ко всем организациям. Некоторые, например api_key_id, применимы только к организациям Claude Console, а другие, например slack_channel_id, — только к организациям Claude Enterprise. Измерение, которое не применимо к вашей организации, равно null в каждой строке, а его фильтр ничему не соответствует; исключение — rbac_group_id, который вместо этого возвращает ошибку, если команды недоступны вашей организации. Справочник API по использованию и затратам перечисляет все измерения, фильтры и значения.

Субъекты

Измерение actor — это субъект, которому приписывается запрос: пользователь, сервисный аккаунт, федеративная облачная идентичность (принципал AWS или Google Cloud для организаций, которые получают доступ к Claude через свою облачную платформу) или, если ни одного из них за запросом нет, сам ключ API. При группировке по actor поле actor каждой строки является объектом, чьё поле type указывает его вид. Использование, которое невозможно приписать какой-либо идентичности, имеет actor: null.

Персональные ключи и ключи сервисных аккаунтов действуют от имени пользователя или сервисного аккаунта, с которым они связаны, поэтому их запросы показывают эту идентичность как actor, а ключ — в api_key_id. Устаревшие ключи рабочих пространств не связаны с идентичностью, поэтому ключ отображается и как actor, и как api_key_id. Исключение — ключ, который Claude Code создаёт, когда участник входит со своей учётной записью Claude Console: он находится в рабочем пространстве Claude Code, и его использование приписывается этому участнику. Запросы, выполненные без ключа API, например из Claude Console или с токеном Workload Identity Federation, имеют api_key_id: null; actor федеративной рабочей нагрузки — это её сервисный аккаунт. Чтобы включить использование без ключа API в фильтр api_key_ids[], добавьте пустую запись: api_key_ids[]=.

Фильтры api_key_ids[] и actor_ids[] отвечают на разные вопросы. api_key_ids[]=apikey_... соответствует каждому запросу, аутентифицированному ключом, кому бы он ни был приписан. actor_ids[]=apikey_... соответствует только запросам, приписанным самому ключу.

Конечная точка использования

GET /v1/organizations/analytics/usage возвращает количество токенов по типам. order_by принимает total_tokens (по умолчанию), output_tokens, uncached_input_tokens, requests или time.

Например, чтобы увидеть использование за неделю для одного рабочего пространства и одного ключа API с разбивкой по уровню обслуживания (по одной строке для каждого уровня, охватывающей всю неделю):

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

Чтобы найти идентификаторы ключей API и рабочих пространств, используйте конечные точки List API Keys и List Workspaces или Claude Console.

Чтобы узнать, какие пользователи, сервисные аккаунты и ключи API выполнили больше всего запросов за месяц:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

Конечная точка затрат

GET /v1/organizations/analytics/cost принимает те же фильтры, измерения и временные интервалы, что и конечная точка /usage. Объект cost каждой строки содержит amount (стоимость после скидок и до применения каких-либо кредитов), list_amount (стоимость по прейскурантным ценам), currency (всегда "USD") и requests. Суммы представлены десятичными строками в центах с шестью знаками после запятой: "41280.000000" — это $412,80 USD. order_by принимает amount (по умолчанию), list_amount или time.

Два дополнительных измерения существуют только на этой конечной точке и не учитываются в ограничении в пять измерений: group_by[]=cost_type разбивает каждую строку на отдельные строки для каждого типа затрат, а group_by[]=token_type разбивает затраты на токены на отдельные строки для каждого типа токенов. limit также не применяется к этим двум измерениям, поэтому страница может содержать больше строк, чем limit. Например, затраты по модели, типу затрат и типу токенов за месяц:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

Для каждой модели ответ содержит пять строк tokens (по одной для каждого типа токенов) плюс по одной строке для web_search, code_execution и session_usage. Одна из этих строк:

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

Объект group содержит все измерения и здесь сокращён. Если указано group_by[]=cost_type или token_type, requests равно null в каждой строке.

Диапазоны дат и временные интервалы

• Временные метки указываются в формате RFC 3339 со смещением UTC, например 2026-09-01T00:00:00Z. starting_at включается в диапазон, а ending_at — нет.
• starting_at должен быть не ранее 1 января 2026 года и в пределах последних 365 дней. Запрос может охватывать не более 31 дня; ending_at по умолчанию равен 31 дню после starting_at или текущему времени, в зависимости от того, что наступает раньше.
• ending_at обязателен, если задан time_bucket_width, а при time_bucket_width=1m запрос может охватывать не более 24 часов.
• Оба конца диапазона округляются вниз до границы интервала в UTC или до часа, если time_bucket_width не задан. Например, при time_bucket_width=1h значение starting_at, равное 2026-09-01T10:43:00Z, обрабатывается как 2026-09-01T10:00:00Z, а значение ending_at, равное 2026-09-01T15:43:00Z, — как 2026-09-01T15:00:00Z, поэтому ответ охватывает период с 10:00 до 15:00 UTC.

Актуальность данных

Каждый ответ включает метку времени data_refreshed_at, и использование после этого момента отсутствует или неполно. Если для какой-либо части запрошенного диапазона данные ещё недоступны, data_refreshed_at имеет значение null, а data пуст. Данные обычно обновляются в течение 4 часов после фактического использования, но это может занять до 24 часов. Значения могут пересматриваться по мере поступления запоздалых событий и выполнения сверки — примерно до 7 дней после окончания календарного месяца. Например, значения за 1 октября могут меняться примерно до 7 ноября. Для стабильных результатов при повторных вызовах задавайте ending_at не позже уже полученного вами значения data_refreshed_at; для окончательных итогов запрашивайте только месяцы, закончившиеся не менее 7 дней назад. Каждая страница запроса с пагинацией читает один и тот же снимок данных, поэтому data_refreshed_at одинаков на всех страницах.

Миграция с Usage and Cost API

Этот раздел предназначен для организаций Claude Console, которые вызывают устаревший Usage and Cost API (/v1/organizations/usage_report/messages и /v1/organizations/cost_report). Ваш ключ Admin API, заголовок anthropic-version, starting_at и ending_at, значения ширины интервала (1m, 1h, 1d), скобочная нотация, имена полей пагинации, а также имена полей токенов и затрат остаются прежними. Что меняется:

Чтобы воспроизвести устаревший ежедневный отчёт, запросите time_bucket_width=1d с тем же group_by[], пролистайте страницы с limit=1000, затем сгруппируйте строки по starting_at и заполните отсутствующие дни нулями. Добавьте order_by=time&order=asc, чтобы получить дни по порядку. Ежедневное использование по моделям за 1 неделю, до:

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

и после:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Ежедневные затраты по рабочему пространству, модели, уровню обслуживания, контекстному окну и географии инференса в разбивке по типу затрат и типу токенов:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

Миграция с отчётов об использовании и затратах Claude Enterprise

Этот раздел предназначен для организаций Claude Enterprise, которые вызывают конечные точки отчётов Claude Enterprise Analytics API usage_report, cost_report, user_usage_report и user_cost_report в /v1/organizations/analytics/. Эти конечные точки являются устаревшими, но по-прежнему поддерживаются. Переходите на /analytics/usage и /analytics/cost, если вам нужно что-либо из следующего:

• Все группы в каждом временном интервале, а не только 100 крупнейших групп в каждом интервале
• Группировка по actor или actor_type вместе с другими измерениями — как для использования, так и для затрат
• Строки, ранжированные по выбранной вами метрике за весь диапазон или упорядоченные по временным интервалам
• Одна интеграция, которая также обслуживает организации Claude Console

Ваш ключ, самая ранняя дата, ретроспектива в 365 дней и диапазон в 31 день, имена и значения фильтров и измерений (кроме user_ids[] и значения продукта Claude Tag), поля actor для пользователей, поля метрик и сумм, data_refreshed_at, правила курсора и ограничение скорости на уровне организации остаются прежними. Единственный новый заголовок — бета-заголовок analytics-usage-cost-2026-08-24. Что меняется:

Затраты по пользователям за месяц, до:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

и после, с добавлением разбивки по продукту:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

Часто задаваемые вопросы

Как представлено рабочее пространство по умолчанию?

Рабочее пространство по умолчанию организации Claude Console имеет собственный ID wrkspc_, как и любое другое рабочее пространство. Строки для рабочего пространства по умолчанию содержат этот ID в workspace_id, и вы можете фильтровать по нему с помощью workspace_ids[]. List Workspaces не включает рабочее пространство по умолчанию, если вы не передадите include_default=true. Чтобы проверить, является ли незнакомый workspace_id рабочим пространством по умолчанию, передайте его в Get Workspace: рабочее пространство по умолчанию возвращает "name": "Default".

Как получить затраты по пользователям для Claude Code?

Вызовите конечную точку затрат с products[]=claude_code&group_by[]=actor. Организации Claude Console также могут использовать Claude Code Analytics API, который предоставляет данные об активности Claude Code по пользователям и оценочные затраты.

См. также

• Usage and Cost API (устаревший)
• API аналитики: какой API аналитики и тип ключа нужны вашей организации
• Claude Code Analytics API
• Справочник Admin API
• Цены