--- title: API de Análise de Uso e Custo url: https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api description: Consulte o uso de tokens e o custo da sua organização do Claude Console ou do Claude Enterprise por modelo, workspace, chave de API, ator e muito mais. --- **A Admin API não está disponível para contas individuais.** Para colaborar com colegas de equipe e adicionar membros, configure sua organização na página [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) no Claude Console. A API de Análise de Uso e Custo informa o uso histórico de tokens e o custo da sua organização, detalhados pelas dimensões que você escolher, como modelo, workspace, chave de API ou o usuário ou conta de serviço por trás de cada solicitação. Para organizações do Claude Console, esses dados são semelhantes aos que as páginas [Usage](https://platform.claude.com/usage) e [Cost](https://platform.claude.com/cost) do Claude Console mostram. A API tem dois endpoints: * `GET /v1/organizations/analytics/usage` informa contagens de tokens e contagens de solicitações. * `GET /v1/organizations/analytics/cost` informa o custo em USD. A API de Análise de Uso e Custo está em beta. Envie o cabeçalho `anthropic-beta: analytics-usage-cost-2026-08-24` e um cabeçalho [`anthropic-version`](https://platform.claude.com/docs/pt-BR/api/versioning) em cada solicitação. O SDK e a CLI `ant` enviam ambos os cabeçalhos para você e buscam as páginas restantes à medida que você lê os resultados, então `limit` define apenas o tamanho da página. Use esta API para: * **Atribuir gastos:** Detalhe o custo e o uso de tokens por workspace, chave de API, modelo, nível de serviço ou pela identidade que fez cada solicitação. * **Encontrar os maiores consumidores:** Classifique os resultados por tokens, solicitações ou custo para responder a perguntas como “quais chaves de API gastam mais este mês?” * **Criar séries temporais:** Divida os resultados em buckets diários, por hora ou por minuto para dashboards e relatórios financeiros. * **Integrar uma única vez:** Os mesmos endpoints, parâmetros e campos de resposta atendem organizações do Claude Console e do Claude Enterprise. **Chave de Admin API necessária** Organizações do Claude Console usam uma [chave de Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys#create-a-key-for-a-claude-console-organization) ou outra [credencial de Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api#authentication). Organizações do Claude Enterprise usam uma chave com o escopo `read:analytics`, criada no claude.ai pelo proprietário principal depois que a Analytics API é habilitada para a organização; consulte [Obtenha acesso à Claude Enterprise Analytics API](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api#get-access-to-the-claude-enterprise-analytics-api). Em ambos os casos, defina a variável de ambiente `ANTHROPIC_API_KEY` com essa chave; os exemplos nesta página leem a chave a partir dela. Se você chamar esses endpoints com uma chave de Admin API, dê ao serviço que coleta esses dados sua própria chave, armazene-a em um gerenciador de segredos e faça a rotação dela regularmente; definir uma [expiração de chave](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-expiration) ao criar a chave impõe a rotação. Sempre que possível, use uma regra de [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation) com o [escopo `org:admin`](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#oauth-scopes) em vez disso, para que o serviço obtenha tokens de curta duração e não haja nenhuma chave de longa duração para vazar. **Claude Platform on AWS:** Ambos os endpoints estão disponíveis. As solicitações usam a URL base e a autenticação do Claude Platform on AWS no lugar de uma chave de Admin API (consulte [Fazendo solicitações](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#making-requests)), e o AWS IAM as autoriza por meio das [ações `ListAccountUsage` e `ListAccountCost`](https://platform.claude.com/docs/pt-BR/api/claude-platform-on-aws-iam-actions#usage-and-cost). Cada solicitação abrange apenas os workspaces na região AWS do endpoint que você chama, então chame o endpoint de cada região para abranger toda a sua organização. `user_profile_id`, `claude_tag_category`, `claude_tag_user_id` e as dimensões do Claude Managed Agents (`agent_id`, `environment_id`, `deployment_id` e `session_id`) são `null` em todas as linhas. **Claude Models on Google Cloud (Anthropic managed):** Ambos os endpoints estão disponíveis. Chame-os por meio da [URL base no nível da organização](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed#making-requests) com credenciais do Google Cloud em vez de uma chave de Admin API. O endpoint `/usage` precisa da [permissão do IAM](https://platform.claude.com/docs/pt-BR/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions) `usageAnalytics.list`, e o endpoint `/cost` precisa de `costAnalytics.list`. ## Início rápido Obtenha o uso diário de tokens da primeira semana de setembro, uma linha para cada modelo e dia: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ time_bucket_width=1d&\ group_by[]=model&\ limit=10" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${row.starting_at} ${row.group.model}: ${row.usage.total_tokens}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day, GroupBy = [BetaAnalyticsUsageGroupBy.Model], Limit = 10, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.StartingAt} {row.Group.Model}: {row.Usage.TotalTokens}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay, GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByModel}, Limit: anthropic.Int(10), }) for rows.Next() { row := rows.Current() fmt.Printf("%s %s: %d\n", row.StartingAt.Format(time.RFC3339), row.Group.Model, row.Usage.TotalTokens) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth; import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY) .addGroupBy(BetaAnalyticsUsageGroupBy.MODEL) .limit(10) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.startingAt() + " " + row.group().model().orElse(null) + ": " + row.usage().totalTokens()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), timeBucketWidth: '1d', groupBy: ['model'], limit: 10, ); foreach ($rows->pagingEachItem() as $row) { $startingAt = $row->startingAt->format(\DateTimeInterface::ATOM); echo "{$startingAt} {$row->group->model}: {$row->usage->totalTokens}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), time_bucket_width: :"1d", group_by: [:model], limit: 10 ) page.auto_paging_each do |row| puts "#{row.starting_at} #{row.group.model}: #{row.usage.total_tokens}" end ``` A resposta tem uma linha para cada modelo e dia que tem uso, com o maior `total_tokens` primeiro. Este exemplo mostra uma única linha: ```json { "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" } ``` **Defina um cabeçalho User-Agent para integrações** Se você estiver construindo uma integração, defina seu cabeçalho User-Agent para ajudar a Anthropic a entender os padrões de uso: ```text wrap User-Agent: YourApp/1.0.0 (https://yourapp.com) ``` ## Como os resultados são estruturados * **Toda linha tem três partes:** `starting_at` e `ending_at` indicam o período que a linha abrange, `group` contém todas as dimensões e `usage` (ou `cost` no endpoint de custo) contém as métricas. * **Dimensões são nulas a menos que agrupadas:** Uma dimensão em `group` é `null` a menos que você a liste em `group_by[]`. Uma dimensão agrupada também é `null` em linhas que não têm valor para ela, como `model` no uso de execução de código. `group_by[]` aceita até cinco dimensões. * **Uma linha para cada combinação:** Cada linha é uma combinação das dimensões agrupadas, e toda combinação que tem uso ou custo aparece exatamente uma vez nas páginas de uma consulta. Sem `group_by[]` e sem `time_bucket_width`, a resposta é uma única linha que totaliza todo o intervalo. * **Time buckets são opcionais:** Defina `time_bucket_width` como `1m`, `1h` ou `1d` para dividir cada combinação por bucket UTC; o `starting_at` e o `ending_at` de cada linha passam a ser os limites do seu bucket. Buckets sem uso ou custo não produzem linhas. * **Classificadas por padrão:** As linhas são ordenadas pela métrica de `order_by` em todo o intervalo, da maior para a menor por padrão (`order=asc` inverte a ordem). Para construir uma série temporal, defina `time_bucket_width` e `order_by=time`. As linhas então retornam um time bucket após o outro, com o time bucket mais recente primeiro por padrão (`order=asc` coloca o mais antigo primeiro), com as maiores linhas primeiro dentro de cada time bucket. Preencha os time buckets vazios com zeros. * **Filtros funcionam junto com o agrupamento:** A maioria das dimensões pelas quais você pode agrupar tem um filtro de lista correspondente em notação de colchetes, como `models[]=claude-opus-5-5`. Repita o parâmetro para passar vários valores, até 100. Vários valores para o mesmo filtro são combinados com OR, e filtros diferentes são combinados com AND. Filtros e `group_by[]` são independentes; você pode filtrar por qualquer dimensão agrupando ou não por ela, ou o inverso. Dimensões como `model` e `actor` se aplicam a todas as organizações. Algumas, como `api_key_id`, se aplicam apenas a organizações do Claude Console, e outras, como `slack_channel_id`, se aplicam apenas a organizações do Claude Enterprise. Uma dimensão que não se aplica à sua organização é `null` em todas as linhas e seu filtro não corresponde a nada; a exceção é `rbac_group_id`, que retorna um erro quando equipes não estão disponíveis para sua organização. A referência da API para [uso](https://platform.claude.com/docs/pt-BR/api/beta/organization/analytics/usage/list) e [custo](https://platform.claude.com/docs/pt-BR/api/beta/organization/analytics/cost/list) lista todas as dimensões, filtros e valores. ### Atores A dimensão `actor` indica a quem uma solicitação é atribuída: um usuário, uma conta de serviço, uma identidade de nuvem federada (um principal da AWS ou do Google Cloud, para organizações que acessam o Claude por meio de sua plataforma de nuvem) ou, quando nenhum desses está por trás da solicitação, a própria chave de API. Quando você agrupa por `actor`, o `actor` de cada linha é um objeto cujo `type` indica de que tipo ele é. O uso que não pode ser atribuído a nenhuma identidade tem `actor: null`. [Chaves pessoais e chaves de conta de serviço](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-types) atuam como o usuário ou a conta de serviço aos quais estão vinculadas, então suas solicitações mostram essa identidade como o `actor` e a chave em `api_key_id`. Chaves de workspace legadas não estão vinculadas a uma identidade, então a chave aparece tanto como o `actor` quanto como o `api_key_id`. A exceção é a chave que o Claude Code cria quando um membro faz login com sua conta do Claude Console: ela fica no [workspace do Claude Code](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#claude-code-workspace), e seu uso é atribuído a esse membro. Solicitações feitas sem uma chave de API, como a partir do Claude Console ou com um token de [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation), têm `api_key_id: null`; o `actor` de uma carga de trabalho federada é sua conta de serviço. Para incluir o uso sem chave de API em um filtro `api_key_ids[]`, adicione uma entrada vazia: `api_key_ids[]=`. Os filtros `api_key_ids[]` e `actor_ids[]` respondem a perguntas diferentes. `api_key_ids[]=apikey_...` corresponde a todas as solicitações que a chave autenticou, independentemente de a quem sejam atribuídas. `actor_ids[]=apikey_...` corresponde apenas às solicitações atribuídas à própria chave. ## Endpoint de uso `GET /v1/organizations/analytics/usage` retorna contagens de tokens por tipo. `order_by` aceita `total_tokens` (o padrão), `output_tokens`, `uncached_input_tokens`, `requests` ou `time`. Por exemplo, para ver uma semana de uso de um workspace e uma chave de API, detalhado por nível de serviço (uma linha para cada nível, abrangendo a semana inteira): ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ 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" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:usage list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-09-08T00:00:00Z \ --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \ --api-key-id apikey_01Rj2N8SVvo6BePZj99NhmiT \ --group-by service_tier ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${row.group.service_tier}: ${row.usage.total_tokens}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), WorkspaceIds = ["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"], ApiKeyIds = ["apikey_01Rj2N8SVvo6BePZj99NhmiT"], GroupBy = [BetaAnalyticsUsageGroupBy.ServiceTier], } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.Group.ServiceTier?.Raw()}: {row.Usage.TotalTokens}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), WorkspaceIDs: []string{"wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"}, APIKeyIDs: []string{"apikey_01Rj2N8SVvo6BePZj99NhmiT"}, GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByServiceTier}, }) for rows.Next() { row := rows.Current() fmt.Printf("%s: %d\n", row.Group.ServiceTier, row.Usage.TotalTokens) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .addWorkspaceId("wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ") .addApiKeyId("apikey_01Rj2N8SVvo6BePZj99NhmiT") .addGroupBy(BetaAnalyticsUsageGroupBy.SERVICE_TIER) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.group().serviceTier().orElse(null) + ": " + row.usage().totalTokens()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), workspaceIDs: ['wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'], apiKeyIDs: ['apikey_01Rj2N8SVvo6BePZj99NhmiT'], groupBy: ['service_tier'], ); foreach ($rows->pagingEachItem() as $row) { echo "{$row->group->serviceTier}: {$row->usage->totalTokens}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), workspace_ids: ["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"], api_key_ids: ["apikey_01Rj2N8SVvo6BePZj99NhmiT"], group_by: [:service_tier] ) page.auto_paging_each do |row| puts "#{row.group.service_tier}: #{row.usage.total_tokens}" end ``` Para consultar IDs de chaves de API e de workspaces, use os endpoints [List API Keys](https://platform.claude.com/docs/pt-BR/api/organization/api_keys/list) e [List Workspaces](https://platform.claude.com/docs/pt-BR/api/organization/workspaces/list) ou o Claude Console. Para descobrir quais usuários, contas de serviço e chaves de API fizeram mais solicitações em um mês: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ group_by[]=actor&\ order_by=requests&\ limit=25" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${JSON.stringify(row.group.actor)}: ${row.usage.requests}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), GroupBy = [BetaAnalyticsUsageGroupBy.Actor], OrderBy = BetaAnalyticsUsageOrderBy.Requests, Limit = 25, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.Group.Actor?.Json}: {row.Usage.Requests}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByActor}, OrderBy: anthropic.BetaAnalyticsUsageOrderByRequests, Limit: anthropic.Int(25), }) for rows.Next() { row := rows.Current() fmt.Printf("%s: %d\n", row.Group.Actor.RawJSON(), row.Usage.Requests) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageOrderBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .addGroupBy(BetaAnalyticsUsageGroupBy.ACTOR) .orderBy(BetaAnalyticsUsageOrderBy.REQUESTS) .limit(25) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.group().actor().orElse(null) + ": " + row.usage().requests().orElse(null)); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), groupBy: ['actor'], orderBy: 'requests', limit: 25, ); foreach ($rows->pagingEachItem() as $row) { $actor = json_encode($row->group->actor); echo "{$actor}: {$row->usage->requests}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), group_by: [:actor], order_by: :requests, limit: 25 ) page.auto_paging_each do |row| puts "#{row.group.actor}: #{row.usage.requests}" end ``` ## Endpoint de custo `GET /v1/organizations/analytics/cost` aceita os mesmos filtros, dimensões e time buckets que o endpoint `/usage`. O objeto `cost` de cada linha contém `amount` (o custo após descontos e antes da aplicação de quaisquer créditos), `list_amount` (o custo a preços de tabela), `currency` (sempre `"USD"`) e `requests`. Os valores são strings decimais em centavos com seis casas decimais: `"41280.000000"` equivale a $412,80 USD. `order_by` aceita `amount` (o padrão), `list_amount` ou `time`. Duas dimensões extras existem apenas neste endpoint e não contam para o limite de cinco dimensões: `group_by[]=cost_type` divide cada linha em uma linha para cada tipo de custo, e `group_by[]=token_type` divide o custo de tokens em uma linha para cada tipo de token. `limit` também não se aplica a essas duas dimensões, então uma página pode conter mais de `limit` linhas. Por exemplo, custo por modelo, tipo de custo e tipo de token para um mês: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ group_by[]=model&\ group_by[]=cost_type&\ group_by[]=token_type" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:cost list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-10-01T00:00:00Z \ --group-by model \ --group-by cost_type \ --group-by token_type ``` ```python Python 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}" ) ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log( `${row.group.model} ${row.group.cost_type} ${row.group.token_type}: ${row.cost.amount}` ); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics.Cost; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Cost.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), GroupBy = [BetaAnalyticsCostGroupBy.Model, BetaAnalyticsCostGroupBy.CostType, BetaAnalyticsCostGroupBy.TokenType], } ); await foreach (var row in page.Paginate()) { Console.WriteLine( $"{row.Group.Model} {row.Group.CostType?.Raw()} {row.Group.TokenType?.Raw()}: {row.Cost.Amount}" ); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), GroupBy: []anthropic.BetaAnalyticsCostGroupBy{anthropic.BetaAnalyticsCostGroupByModel, anthropic.BetaAnalyticsCostGroupByCostType, anthropic.BetaAnalyticsCostGroupByTokenType}, }) for rows.Next() { row := rows.Current() fmt.Printf("%s %s %s: %s\n", row.Group.Model, row.Group.CostType, row.Group.TokenType, row.Cost.Amount) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy; import com.anthropic.models.beta.organization.analytics.cost.CostListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = CostListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .addGroupBy(BetaAnalyticsCostGroupBy.MODEL) .addGroupBy(BetaAnalyticsCostGroupBy.COST_TYPE) .addGroupBy(BetaAnalyticsCostGroupBy.TOKEN_TYPE) .build(); var rows = client.beta().organization().analytics().cost().list(params); for (var row : rows.autoPager()) { var group = row.group(); IO.println( group.model().orElse(null) + " " + group.costType().orElse(null) + " " + group.tokenType().orElse(null) + ": " + row.cost().amount() ); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), groupBy: ['model', 'cost_type', 'token_type'], ); foreach ($rows->pagingEachItem() as $row) { $group = $row->group; echo "{$group->model} {$group->costType} {$group->tokenType}: {$row->cost->amount}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.cost.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), group_by: [:model, :cost_type, :token_type] ) page.auto_paging_each do |row| group = row.group puts "#{group.model} #{group.cost_type} #{group.token_type}: #{row.cost.amount}" end ``` Para cada modelo, a resposta tem cinco linhas `tokens` (uma para cada tipo de token) mais uma linha para cada um de `web_search`, `code_execution` e `session_usage`. Uma dessas linhas: ```json { "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 } } ``` O objeto `group` contém todas as dimensões e está abreviado aqui. Com `group_by[]=cost_type` ou `token_type` especificado, `requests` é `null` em todas as linhas. Solicitações atendidas sob um compromisso de Priority Tier aparecem no endpoint de uso com `service_tier: "priority"`, mas contribuem com custo de tokens zero para `amount` e `list_amount`, porque seu compromisso as cobre; a taxa do compromisso é cobrada separadamente e não está nesses dados. A pesquisa na web nessas solicitações é cobrada à taxa padrão. Solicitações além da sua capacidade comprometida são atendidas e precificadas no nível padrão. ## Intervalos de datas e time buckets * Os timestamps seguem o RFC 3339 com um deslocamento UTC, por exemplo `2026-09-01T00:00:00Z`. `starting_at` é inclusivo e `ending_at` é exclusivo. * `starting_at` deve ser em ou após 1º de janeiro de 2026 e dentro dos últimos 365 dias. Uma solicitação pode abranger no máximo 31 dias; `ending_at` tem como padrão 31 dias após `starting_at` ou o horário atual, o que ocorrer primeiro. * `ending_at` é obrigatório sempre que `time_bucket_width` estiver definido, e com `time_bucket_width=1m` uma solicitação pode abranger no máximo 24 horas. * Ambas as extremidades do intervalo são arredondadas para baixo até um limite de bucket UTC, ou até a hora quando `time_bucket_width` não está definido. Por exemplo, com `time_bucket_width=1h`, um `starting_at` de `2026-09-01T10:43:00Z` é tratado como `2026-09-01T10:00:00Z` e um `ending_at` de `2026-09-01T15:43:00Z` como `2026-09-01T15:00:00Z`, então a resposta cobre das 10:00 às 15:00 UTC. ## Atualização dos dados Toda resposta inclui um timestamp `data_refreshed_at`, e o uso posterior a esse momento está ausente ou parcial. Quando ainda não há dados disponíveis para nenhuma parte do intervalo solicitado, `data_refreshed_at` é `null` e `data` fica vazio. Os dados normalmente são atualizados em até 4 horas após o uso subjacente e podem levar até 24 horas. Os valores podem ser revisados à medida que eventos atrasados chegam e a reconciliação é executada, até cerca de 7 dias após o fim do mês civil. Por exemplo, os valores de 1º de outubro podem mudar até cerca de 7 de novembro. Para obter resultados estáveis em chamadas repetidas, defina `ending_at` em ou antes de um `data_refreshed_at` que você já tenha visto; para totais finais, consulte apenas meses que terminaram há pelo menos 7 dias. Todas as páginas de uma consulta paginada leem o mesmo snapshot de dados, então `data_refreshed_at` é idêntico em todas as páginas. ## Migrar da API de Uso e Custo Esta seção é para organizações do Claude Console que chamam a [API de Uso e Custo](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-api) legada (`/v1/organizations/usage_report/messages` e `/v1/organizations/cost_report`). Sua chave de Admin API, o cabeçalho `anthropic-version`, `starting_at` e `ending_at`, os valores de largura de bucket (`1m`, `1h`, `1d`), a notação de colchetes, os nomes dos campos de paginação e os nomes dos campos de tokens e custo permanecem os mesmos. O que muda: | API de Uso e Custo | API de Análise de Uso e Custo | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sem cabeçalho beta | `anthropic-beta: analytics-usage-cost-2026-08-24` em cada solicitação | | Os dados normalmente aparecem em até 5 minutos | Os dados normalmente são atualizados em até 4 horas e podem levar até 24 horas (consulte [Atualização dos dados](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#data-freshness)) | | `data` é uma lista de time buckets, do mais antigo para o mais recente, incluindo os vazios, cada um com uma lista `results` cujas entradas contêm dimensões e métricas lado a lado | `data` é uma lista de linhas classificadas por `order_by`, cada uma com seus próprios `starting_at` e `ending_at`, dimensões em `group` e métricas em `usage` ou `cost`. Combinações sem uso ou custo não têm linha. | | `bucket_width`, padrão `1d` | `time_bucket_width`, sem padrão. Passe `time_bucket_width=1d` para manter linhas diárias; omita-o para totais de todo o intervalo. O endpoint de custo também aceita todos os filtros e buckets `1m` e `1h`. | | `limit` conta time buckets por página | `limit` conta linhas por página (de 1 a 1.000, padrão 20), então o número de páginas depende de quantas combinações têm dados | | Qualquer intervalo de datas, paginado para frente por bucket | `starting_at` em ou após 1º de janeiro de 2026 e dentro dos últimos 365 dias, no máximo 31 dias por solicitação, `ending_at` obrigatório com `time_bucket_width` e no máximo 24 horas com buckets `1m` (consulte [Intervalos de datas e time buckets](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#date-ranges-and-time-buckets)). Divida intervalos mais longos em várias solicitações. | | `account_ids[]`, `service_account_ids[]`, `group_by[]=account_id`, `group_by[]=service_account_id` | `actor_ids[]` com os mesmos IDs com prefixo, e `group_by[]=actor` ou `actor_type`; leia `actor.user_id` ou `actor.service_account_id`. Consulte [Atores](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#actors). | | `context_window[]` | `context_windows[]` | | `group_by[]=description` no relatório de custo, com uma string `description` | Sem `description`. Em vez disso, agrupe pelas dimensões estruturadas: qualquer uma de `model`, `cost_type`, `token_type`, `context_window`, `service_tier`, `inference_geo` e `speed`, todas as quais cabem em uma única solicitação. | | Uma chave de API ou ID de workspace desconhecido retorna um erro | Não corresponde a nada, incluindo um nome de `models[]` digitado incorretamente. Cada lista aceita até 100 valores. | | `workspace_id: null` para o workspace padrão | O `workspace_id` real do workspace padrão (consulte [Como o workspace padrão é representado?](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-analytics-api#how-is-the-default-workspace-represented)) | | `inference_geo: "not_available"` e `service_tier: "standard"` em uso sem geografia de inferência ou nível | `null` para ambos. `inference_geos[]=not_available` ainda corresponde às linhas sem geografia de inferência. | | O `service_tier` de custo é `standard` ou `batch`; `amount` como `"123.45"` | O nível real; `amount` com seis casas decimais, como `"123.450000"`, mais `list_amount`. | | Execução de código não aparece no relatório de uso; sem contagem de solicitações | A execução de código aparece como linhas de uso com `model: null`; adiciona `requests` em ambos os endpoints e `total_tokens` nas linhas de uso | Para reproduzir o relatório diário legado, solicite `time_bucket_width=1d` com o mesmo `group_by[]`, percorra as páginas com `limit=1000` e, em seguida, agrupe as linhas por `starting_at` e preencha os dias ausentes com zeros. Adicione `order_by=time&order=asc` para obter os dias em ordem. Uso diário por modelo durante 1 semana, antes: ```bash cURL 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" ``` e depois: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ group_by[]=model&\ time_bucket_width=1d&\ limit=1000" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { console.log(`${row.starting_at} ${row.group.model}: ${row.usage.total_tokens}`); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Usage; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Usage.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day, GroupBy = [BetaAnalyticsUsageGroupBy.Model], Limit = 1000, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.StartingAt} {row.Group.Model}: {row.Usage.TotalTokens}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Usage.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUsageListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay, GroupBy: []anthropic.BetaAnalyticsUsageGroupBy{anthropic.BetaAnalyticsUsageGroupByModel}, Limit: anthropic.Int(1000), }) for rows.Next() { row := rows.Current() fmt.Printf("%s %s: %d\n", row.StartingAt.Format(time.RFC3339), row.Group.Model, row.Usage.TotalTokens) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth; import com.anthropic.models.beta.organization.analytics.usage.BetaAnalyticsUsageGroupBy; import com.anthropic.models.beta.organization.analytics.usage.UsageListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UsageListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY) .addGroupBy(BetaAnalyticsUsageGroupBy.MODEL) .limit(1000) .build(); var rows = client.beta().organization().analytics().usage().list(params); for (var row : rows.autoPager()) { IO.println(row.startingAt() + " " + row.group().model().orElse(null) + ": " + row.usage().totalTokens()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->usage->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), timeBucketWidth: '1d', groupBy: ['model'], limit: 1000, ); foreach ($rows->pagingEachItem() as $row) { $startingAt = $row->startingAt->format(\DateTimeInterface::ATOM); echo "{$startingAt} {$row->group->model}: {$row->usage->totalTokens}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.usage.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), time_bucket_width: :"1d", group_by: [:model], limit: 1000 ) page.auto_paging_each do |row| puts "#{row.starting_at} #{row.group.model}: #{row.usage.total_tokens}" end ``` Custo diário por workspace, modelo, nível de serviço, janela de contexto e geografia de inferência, dividido por tipo de custo e tipo de token: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-09-08T00:00:00Z&\ time_bucket_width=1d&\ group_by[]=workspace_id&\ group_by[]=model&\ group_by[]=service_tier&\ group_by[]=context_window&\ group_by[]=inference_geo&\ group_by[]=cost_type&\ group_by[]=token_type&\ limit=1000" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant 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 \ --group-by model \ --group-by service_tier \ --group-by context_window \ --group-by inference_geo \ --group-by cost_type \ --group-by token_type \ --limit 1000 ``` ```python Python 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}" ) ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { const { group } = row; console.log( `${row.starting_at} ${group.workspace_id} ${group.model} ${group.service_tier} ` + `${group.context_window} ${group.inference_geo} ${group.cost_type} ${group.token_type}: ` + `${row.cost.amount}` ); } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Cost; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Cost.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-09-08T00:00:00Z"), TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day, GroupBy = [ BetaAnalyticsCostGroupBy.WorkspaceID, BetaAnalyticsCostGroupBy.Model, BetaAnalyticsCostGroupBy.ServiceTier, BetaAnalyticsCostGroupBy.ContextWindow, BetaAnalyticsCostGroupBy.InferenceGeo, BetaAnalyticsCostGroupBy.CostType, BetaAnalyticsCostGroupBy.TokenType, ], Limit = 1000, } ); await foreach (var row in page.Paginate()) { var group = row.Group; Console.WriteLine( $"{row.StartingAt} {group.WorkspaceID} {group.Model} {group.ServiceTier?.Raw()} " + $"{group.ContextWindow?.Raw()} {group.InferenceGeo?.Raw()} {group.CostType?.Raw()} " + $"{group.TokenType?.Raw()}: {row.Cost.Amount}" ); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.September, 8, 0, 0, 0, 0, time.UTC)), TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay, GroupBy: []anthropic.BetaAnalyticsCostGroupBy{ anthropic.BetaAnalyticsCostGroupByWorkspaceID, anthropic.BetaAnalyticsCostGroupByModel, anthropic.BetaAnalyticsCostGroupByServiceTier, anthropic.BetaAnalyticsCostGroupByContextWindow, anthropic.BetaAnalyticsCostGroupByInferenceGeo, anthropic.BetaAnalyticsCostGroupByCostType, anthropic.BetaAnalyticsCostGroupByTokenType, }, Limit: anthropic.Int(1000), }) for rows.Next() { row := rows.Current() group := row.Group fmt.Printf("%s %s %s %s %s %s %s %s: %s\n", row.StartingAt.Format(time.RFC3339), group.WorkspaceID, group.Model, group.ServiceTier, group.ContextWindow, group.InferenceGeo, group.CostType, group.TokenType, row.Cost.Amount) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth; import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy; import com.anthropic.models.beta.organization.analytics.cost.CostListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = CostListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-09-08T00:00:00Z")) .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY) .addGroupBy(BetaAnalyticsCostGroupBy.WORKSPACE_ID) .addGroupBy(BetaAnalyticsCostGroupBy.MODEL) .addGroupBy(BetaAnalyticsCostGroupBy.SERVICE_TIER) .addGroupBy(BetaAnalyticsCostGroupBy.CONTEXT_WINDOW) .addGroupBy(BetaAnalyticsCostGroupBy.INFERENCE_GEO) .addGroupBy(BetaAnalyticsCostGroupBy.COST_TYPE) .addGroupBy(BetaAnalyticsCostGroupBy.TOKEN_TYPE) .limit(1000) .build(); var rows = client.beta().organization().analytics().cost().list(params); for (var row : rows.autoPager()) { var group = row.group(); IO.println( row.startingAt() + " " + group.workspaceId().orElse(null) + " " + group.model().orElse(null) + " " + group.serviceTier().orElse(null) + " " + group.contextWindow().orElse(null) + " " + group.inferenceGeo().orElse(null) + " " + group.costType().orElse(null) + " " + group.tokenType().orElse(null) + ": " + row.cost().amount() ); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-09-08T00:00:00Z'), timeBucketWidth: '1d', groupBy: [ 'workspace_id', 'model', 'service_tier', 'context_window', 'inference_geo', 'cost_type', 'token_type', ], limit: 1000, ); foreach ($rows->pagingEachItem() as $row) { $startingAt = $row->startingAt->format(\DateTimeInterface::ATOM); $group = $row->group; echo "{$startingAt} {$group->workspaceID} {$group->model} {$group->serviceTier} " . "{$group->contextWindow} {$group->inferenceGeo} {$group->costType} {$group->tokenType}: " . "{$row->cost->amount}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.cost.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 9, 8), time_bucket_width: :"1d", group_by: [ :workspace_id, :model, :service_tier, :context_window, :inference_geo, :cost_type, :token_type ], limit: 1000 ) page.auto_paging_each do |row| group = row.group puts "#{row.starting_at} #{group.workspace_id} #{group.model} #{group.service_tier} " \ "#{group.context_window} #{group.inference_geo} #{group.cost_type} #{group.token_type}: " \ "#{row.cost.amount}" end ``` ## Migrar dos relatórios de uso e custo do Claude Enterprise Esta seção é para organizações do Claude Enterprise que chamam os endpoints de relatório da [Claude Enterprise Analytics API](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api) `usage_report`, `cost_report`, `user_usage_report` e `user_cost_report` em `/v1/organizations/analytics/`. Esses endpoints são legados e continuam sendo suportados. Migre para `/analytics/usage` e `/analytics/cost` quando quiser qualquer um dos seguintes: * Todos os grupos em cada time bucket, em vez dos 100 principais grupos em cada bucket * Agrupamento por `actor` ou `actor_type` junto com outras dimensões, tanto em uso quanto em custo * Linhas classificadas por uma métrica de sua escolha em todo o intervalo, ou ordenadas por time bucket * Uma única integração que também atende organizações do Claude Console Sua chave, a data mais antiga, o período retroativo de 365 dias e o intervalo de 31 dias, os nomes e valores de filtros e dimensões (exceto `user_ids[]` e o valor de produto do Claude Tag), os campos `actor` de usuário, os campos de métricas e valores, `data_refreshed_at`, as regras de cursor e o [limite de taxa no nível da organização](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api#working-with-the-api) permanecem os mesmos. O único cabeçalho novo é o cabeçalho beta `analytics-usage-cost-2026-08-24`. O que muda: | Relatórios do Claude Enterprise | API de Análise de Uso e Custo | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `usage_report` e `cost_report` retornam time buckets, do mais antigo para o mais recente, incluindo os vazios, cada um contendo no máximo seus 100 principais grupos; `bucket_width` tem padrão `1d` e `limit` conta buckets | Linhas abrangendo todas as combinações com dados, classificadas por `order_by`, cada uma com seus próprios `starting_at` e `ending_at`, dimensões em `group` e métricas em `usage` ou `cost`. `time_bucket_width` é opcional e `limit` conta linhas. | | O parâmetro de time bucket é `bucket_width` | É `time_bucket_width`, com os mesmos valores | | Em `usage_report` e `cost_report`, `ending_at` é opcional com `bucket_width` e buckets `1m` podem abranger até 31 dias | `ending_at` obrigatório com `time_bucket_width`; buckets `1m` abrangem no máximo 24 horas por solicitação | | `user_usage_report` e `user_cost_report` retornam uma linha por usuário | `group_by[]=actor&actor_types[]=user_actor`. Sem o filtro, você também obtém linhas para identidades que não são usuários e uma linha `actor: null` para uso não atribuído. | | O uso do Claude Tag tem `product: "claude-tag"` | `product: "claude_tag"`; `products[]` aceita qualquer uma das grafias | | Um nome de `models[]` não reconhecido retorna um erro 400 | Não corresponde a nada | | `user_ids[]` | `actor_ids[]` com os mesmos IDs com prefixo `user_...` | | `exclude_deleted_users` nos relatórios por usuário | Requer `group_by[]=actor`; sem ele, a solicitação retorna um erro 400. Remove apenas as linhas cujo `actor` é um usuário com `deleted: true`; as linhas de outras identidades e as linhas com `actor: null` permanecem. | Custo por usuário em um mês, antes: ```bash cURL curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ limit=100" \ -H "anthropic-version: 2023-06-01" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:user-cost-report list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-10-01T00:00:00Z \ --limit 100 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await client.beta.organization.analytics.userCostReport.list({ starting_at: "2026-09-01T00:00:00Z", ending_at: "2026-10-01T00:00:00Z", limit: 100 }); for await (const row of rows) { console.log(`${row.actor.user_id}: ${row.amount}`); } ``` ```csharp C# AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.UserCostReport.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), Limit = 100, } ); await foreach (var row in page.Paginate()) { Console.WriteLine($"{row.Actor.UserID}: {row.Amount}"); } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.UserCostReport.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUserCostReportListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), Limit: anthropic.Int(100), }) for rows.Next() { row := rows.Current() fmt.Printf("%s: %s\n", row.Actor.UserID, row.Amount) } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.usercostreport.UserCostReportListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = UserCostReportListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .limit(100) .build(); var rows = client.beta().organization().analytics().userCostReport().list(params); for (var row : rows.autoPager()) { IO.println(row.actor().userId() + ": " + row.amount()); } } ``` ```php PHP $client = new Client(); $rows = $client->beta->organization->analytics->userCostReport->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), limit: 100, ); foreach ($rows->pagingEachItem() as $row) { echo "{$row->actor->userID}: {$row->amount}\n"; } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.user_cost_report.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), limit: 100 ) page.auto_paging_each do |row| puts "#{row.actor.user_id}: #{row.amount}" end ``` e depois, adicionando um detalhamento por produto: ```bash cURL curl --globoff "https://api.anthropic.com/v1/organizations/analytics/cost?\ starting_at=2026-09-01T00:00:00Z&\ ending_at=2026-10-01T00:00:00Z&\ group_by[]=actor&\ group_by[]=product&\ actor_types[]=user_actor&\ limit=100" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: analytics-usage-cost-2026-08-24" \ -H "x-api-key: $ANTHROPIC_API_KEY" ``` ```bash CLI ant beta:organization:analytics:cost list \ --starting-at 2026-09-01T00:00:00Z \ --ending-at 2026-10-01T00:00:00Z \ --actor-type user_actor \ --group-by actor \ --group-by product \ --limit 100 ``` ```python Python 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}") ``` ```typescript TypeScript const client = new Anthropic(); const rows = await 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 await (const row of rows) { const { actor } = row.group; if (actor?.type === "user_actor") { console.log(`${actor.user_id} ${row.group.product}: ${row.cost.amount}`); } } ``` ```csharp C# using Anthropic.Models.Beta.Organization.Analytics; using Anthropic.Models.Beta.Organization.Analytics.Cost; AnthropicClient client = new(); var page = await client.Beta.Organization.Analytics.Cost.List( new() { StartingAt = DateTimeOffset.Parse("2026-09-01T00:00:00Z"), EndingAt = DateTimeOffset.Parse("2026-10-01T00:00:00Z"), ActorTypes = [BetaAnalyticsActorType.UserActor], GroupBy = [BetaAnalyticsCostGroupBy.Actor, BetaAnalyticsCostGroupBy.Product], Limit = 100, } ); await foreach (var row in page.Paginate()) { if (row.Group.Actor is { } actor && actor.TryPickReportUser(out var user)) { Console.WriteLine($"{user.UserID} {row.Group.Product}: {row.Cost.Amount}"); } } ``` ```go Go client := anthropic.NewClient() rows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{ StartingAt: time.Date(2026, time.September, 1, 0, 0, 0, 0, time.UTC), EndingAt: anthropic.Time(time.Date(2026, time.October, 1, 0, 0, 0, 0, time.UTC)), ActorTypes: []anthropic.BetaAnalyticsActorType{anthropic.BetaAnalyticsActorTypeUserActor}, GroupBy: []anthropic.BetaAnalyticsCostGroupBy{anthropic.BetaAnalyticsCostGroupByActor, anthropic.BetaAnalyticsCostGroupByProduct}, Limit: anthropic.Int(100), }) for rows.Next() { row := rows.Current() if user, ok := row.Group.Actor.AsAny().(anthropic.BetaAnalyticsReportUserActor); ok { fmt.Printf("%s %s: %s\n", user.UserID, row.Group.Product, row.Cost.Amount) } } if err := rows.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.beta.organization.analytics.BetaAnalyticsActorType; import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy; import com.anthropic.models.beta.organization.analytics.cost.CostListParams; import java.time.OffsetDateTime; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = CostListParams.builder() .startingAt(OffsetDateTime.parse("2026-09-01T00:00:00Z")) .endingAt(OffsetDateTime.parse("2026-10-01T00:00:00Z")) .addActorType(BetaAnalyticsActorType.USER_ACTOR) .addGroupBy(BetaAnalyticsCostGroupBy.ACTOR) .addGroupBy(BetaAnalyticsCostGroupBy.PRODUCT) .limit(100) .build(); var rows = client.beta().organization().analytics().cost().list(params); for (var row : rows.autoPager()) { row.group().actor().flatMap(actor -> actor.user()).ifPresent(user -> IO.println(user.userId() + " " + row.group().product().orElse(null) + ": " + row.cost().amount()) ); } } ``` ```php PHP use Anthropic\Beta\Organization\Analytics\AnalyticsReportUserActor; // ... $client = new Client(); $rows = $client->beta->organization->analytics->cost->list( startingAt: new \DateTimeImmutable('2026-09-01T00:00:00Z'), endingAt: new \DateTimeImmutable('2026-10-01T00:00:00Z'), actorTypes: ['user_actor'], groupBy: ['actor', 'product'], limit: 100, ); foreach ($rows->pagingEachItem() as $row) { $actor = $row->group->actor; if ($actor instanceof AnalyticsReportUserActor) { echo "{$actor->userID} {$row->group->product}: {$row->cost->amount}\n"; } } ``` ```ruby Ruby client = Anthropic::Client.new page = client.beta.organization.analytics.cost.list( starting_at: Time.utc(2026, 9, 1), ending_at: Time.utc(2026, 10, 1), actor_types: [:user_actor], group_by: [:actor, :product], limit: 100 ) page.auto_paging_each do |row| actor = row.group.actor if actor.is_a?(Anthropic::Models::Beta::Organization::BetaAnalyticsReportUserActor) puts "#{actor.user_id} #{row.group.product}: #{row.cost.amount}" end end ``` ## Perguntas frequentes ### Como o workspace padrão é representado? O workspace padrão de uma organização do Claude Console tem seu próprio ID `wrkspc_`, como qualquer outro workspace. As linhas do workspace padrão têm esse ID em `workspace_id`, e você pode filtrar por ele com `workspace_ids[]`. [List Workspaces](https://platform.claude.com/docs/pt-BR/api/organization/workspaces/list) omite o workspace padrão, a menos que você passe `include_default=true`. Para verificar se um `workspace_id` desconhecido é o workspace padrão, passe-o para [Get Workspace](https://platform.claude.com/docs/pt-BR/api/organization/workspaces/retrieve): o workspace padrão retorna `"name": "Default"`. ### Como obtenho o custo por usuário do Claude Code? Chame o endpoint de custo com `products[]=claude_code&group_by[]=actor`. Organizações do Claude Console também podem usar a [Claude Code Analytics API](https://platform.claude.com/docs/pt-BR/manage-claude/claude-code-analytics-api), que informa a atividade do Claude Code por usuário e o custo estimado. ## Veja também * [API de Uso e Custo](https://platform.claude.com/docs/pt-BR/manage-claude/usage-cost-api) (legado) * [APIs de Analytics](https://platform.claude.com/docs/pt-BR/manage-claude/analytics-api): de qual API de Analytics e de qual tipo de chave sua organização precisa * [Claude Code Analytics API](https://platform.claude.com/docs/pt-BR/manage-claude/claude-code-analytics-api) * [Referência da Admin API](https://platform.claude.com/docs/pt-BR/api/beta/organization) * [Preços](https://platform.claude.com/docs/pt-BR/about-claude/pricing)