--- title: API Usage and Cost Analytics url: https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api description: Interroga l'utilizzo dei token e i costi della tua organizzazione Claude Console o Claude Enterprise per modello, workspace, chiave API, attore e altro ancora. --- **L’Admin API non è disponibile per gli account individuali.** Per collaborare con i colleghi e aggiungere membri, configura la tua organizzazione nella pagina [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) nella Claude Console. L’API Usage and Cost Analytics riporta l’utilizzo storico dei token e i costi della tua organizzazione, suddivisi in base alle dimensioni che scegli, come modello, workspace, chiave API o l’utente o l’account di servizio dietro ogni richiesta. Per le organizzazioni Claude Console, questi dati sono simili a quelli mostrati nelle pagine [Usage](https://platform.claude.com/usage) e [Cost](https://platform.claude.com/cost) della Claude Console. L’API ha due endpoint: * `GET /v1/organizations/analytics/usage` riporta il numero di token e il numero di richieste. * `GET /v1/organizations/analytics/cost` riporta i costi in USD. L’API Usage and Cost Analytics è in beta. Invia l’header `anthropic-beta: analytics-usage-cost-2026-08-24` e un header [`anthropic-version`](https://platform.claude.com/docs/it/api/versioning) in ogni richiesta. L’SDK e la CLI `ant` inviano entrambi gli header per te e recuperano le pagine rimanenti mentre leggi i risultati, quindi `limit` imposta solo la dimensione della pagina. Usa questa API per: * **Attribuire la spesa:** suddividi il costo e l’utilizzo dei token per workspace, chiave API, modello, livello di servizio o identità che ha effettuato ciascuna richiesta. * **Trovare i maggiori consumatori:** ordina i risultati per token, richieste o costo per rispondere a domande come “quali chiavi API spendono di più questo mese?” * **Costruire serie temporali:** suddividi i risultati in intervalli giornalieri, orari o al minuto per dashboard e report finanziari. * **Integrare una sola volta:** gli stessi endpoint, parametri e campi di risposta servono le organizzazioni Claude Console e Claude Enterprise. **Chiave Admin API richiesta** Le organizzazioni Claude Console usano una [chiave Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api-keys#create-a-key-for-a-claude-console-organization) o un’altra [credenziale Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api#authentication). Le organizzazioni Claude Enterprise usano una chiave con lo scope `read:analytics`, creata in claude.ai dal proprietario principale dopo che l’Analytics API è stata abilitata per l’organizzazione; consulta [Ottenere l’accesso alla Claude Enterprise Analytics API](https://platform.claude.com/docs/it/manage-claude/analytics-api#get-access-to-the-claude-enterprise-analytics-api). In entrambi i casi, imposta la variabile d’ambiente `ANTHROPIC_API_KEY` su quella chiave; gli esempi in questa pagina leggono la chiave da essa. Se chiami questi endpoint con una chiave Admin API, assegna al servizio che raccoglie questi dati una chiave dedicata, conservala in un gestore di segreti e ruotala regolarmente; impostare una [scadenza della chiave](https://platform.claude.com/docs/it/manage-claude/authentication#key-expiration) quando crei la chiave impone la rotazione. Dove possibile, usa invece una regola di [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation) con lo [scope `org:admin`](https://platform.claude.com/docs/it/manage-claude/wif-reference#oauth-scopes), in modo che il servizio ottenga token di breve durata e non ci sia alcuna chiave di lunga durata che possa essere divulgata. **Claude Platform on AWS:** Entrambi gli endpoint sono disponibili. Le richieste usano l’URL di base e l’autenticazione di Claude Platform on AWS al posto di una chiave Admin API (vedi [Effettuare richieste](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#making-requests)), e AWS IAM le autorizza tramite le [azioni `ListAccountUsage` e `ListAccountCost`](https://platform.claude.com/docs/it/api/claude-platform-on-aws-iam-actions#usage-and-cost). Ogni richiesta copre solo i workspace nella regione AWS dell’endpoint che chiami, quindi chiama l’endpoint di ciascuna regione per coprire l’intera organizzazione. `user_profile_id`, `claude_tag_category`, `claude_tag_user_id` e le dimensioni di Claude Managed Agents (`agent_id`, `environment_id`, `deployment_id` e `session_id`) sono `null` in ogni riga. **Claude Models on Google Cloud (Anthropic managed):** Entrambi gli endpoint sono disponibili. Chiamali tramite l’[URL di base a livello di organizzazione](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed#making-requests) con le credenziali Google Cloud invece di una chiave Admin API. L’endpoint `/usage` richiede l’[autorizzazione IAM](https://platform.claude.com/docs/it/api/claude-models-on-google-cloud-anthropic-managed-iam-permissions) `usageAnalytics.list`, e l’endpoint `/cost` richiede `costAnalytics.list`. ## Avvio rapido Ottieni l’utilizzo giornaliero dei token per la prima settimana di settembre, con una riga per ciascun modello e giorno: ```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 ``` La risposta contiene una riga per ciascun modello e giorno con utilizzo, a partire dal valore di `total_tokens` più alto. Questo esempio mostra una singola riga: ```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" } ``` **Imposta un header User-Agent per le integrazioni** Se stai creando un’integrazione, imposta il tuo header User-Agent per aiutare Anthropic a comprendere i modelli di utilizzo: ```text wrap User-Agent: YourApp/1.0.0 (https://yourapp.com) ``` ## Come sono strutturati i risultati * **Ogni riga ha tre parti:** `starting_at` e `ending_at` indicano il periodo coperto dalla riga, `group` contiene ogni dimensione e `usage` (o `cost` nell’endpoint dei costi) contiene le metriche. * **Le dimensioni sono null se non raggruppate:** una dimensione in `group` è `null` a meno che tu non la elenchi in `group_by[]`. Una dimensione raggruppata è `null` anche nelle righe che non hanno un valore per essa, come `model` nell’utilizzo dell’esecuzione di codice. `group_by[]` accetta fino a cinque dimensioni. * **Una riga per ciascuna combinazione:** ogni riga è una combinazione delle dimensioni raggruppate, e ogni combinazione con utilizzo o costo compare esattamente una volta tra le pagine di una query. Senza `group_by[]` e senza `time_bucket_width`, la risposta è una singola riga che totalizza l’intero intervallo. * **Gli intervalli temporali sono facoltativi:** imposta `time_bucket_width` su `1m`, `1h` o `1d` per suddividere ciascuna combinazione per intervallo UTC; `starting_at` e `ending_at` di ogni riga corrispondono quindi ai limiti del relativo intervallo. Gli intervalli senza utilizzo o costo non producono righe. * **Ordinate per classifica per impostazione predefinita:** Le righe sono ordinate in base alla metrica `order_by` sull’intero intervallo, dalla più grande per impostazione predefinita (`order=asc` inverte l’ordine). Per costruire una serie temporale, imposta `time_bucket_width` e `order_by=time`. Le righe vengono quindi restituite un intervallo temporale dopo l’altro, con l’intervallo più recente per primo per impostazione predefinita (`order=asc` mette per primo il più vecchio), e con le righe più grandi per prime all’interno di ogni intervallo. Riempi gli intervalli vuoti con zeri. * **I filtri funzionano insieme al raggruppamento:** la maggior parte delle dimensioni per cui puoi raggruppare ha un filtro a lista corrispondente in notazione con parentesi quadre, come `models[]=claude-opus-5-5`. Ripeti il parametro per passare più valori, fino a 100. Più valori per lo stesso filtro sono combinati con OR, mentre filtri diversi sono combinati con AND. I filtri e `group_by[]` sono indipendenti; puoi filtrare per qualsiasi dimensione con o senza raggrupparla, o viceversa. Dimensioni come `model` e `actor` si applicano a ogni organizzazione. Alcune, come `api_key_id`, si applicano solo alle organizzazioni Claude Console, e altre, come `slack_channel_id`, si applicano solo alle organizzazioni Claude Enterprise. Una dimensione che non si applica alla tua organizzazione è `null` in ogni riga e il suo filtro non corrisponde a nulla; l’eccezione è `rbac_group_id`, che restituisce invece un errore quando i team non sono disponibili per la tua organizzazione. Il riferimento API per [utilizzo](https://platform.claude.com/docs/it/api/beta/organization/analytics/usage/list) e [costi](https://platform.claude.com/docs/it/api/beta/organization/analytics/cost/list) elenca ogni dimensione, filtro e valore. ### Attori La dimensione `actor` indica a chi è attribuita una richiesta: un utente, un account di servizio, un’identità cloud federata (un principal AWS o Google Cloud, per le organizzazioni che accedono a Claude tramite la propria piattaforma cloud) oppure, quando nessuno di questi è dietro la richiesta, la chiave API stessa. Quando raggruppi per `actor`, l’`actor` di ogni riga è un oggetto il cui `type` indica di che tipo si tratta. L’utilizzo che non può essere attribuito ad alcuna identità ha `actor: null`. Le [chiavi personali e le chiavi di service account](https://platform.claude.com/docs/it/manage-claude/authentication#key-types) agiscono come l’utente o il service account a cui sono collegate, quindi le loro richieste mostrano quell’identità come `actor` e la chiave in `api_key_id`. Le chiavi di workspace legacy non sono collegate a un’identità, quindi la chiave compare sia come `actor` sia come `api_key_id`. L’eccezione è la chiave che Claude Code crea quando un membro accede con il proprio account Claude Console: si trova nel [workspace di Claude Code](https://platform.claude.com/docs/it/manage-claude/workspaces#claude-code-workspace) e il suo utilizzo è attribuito a quel membro. Le richieste effettuate senza una chiave API, ad esempio dalla Claude Console o con un token di [Workload Identity Federation](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation), hanno `api_key_id: null`; l’`actor` di un workload federato è il suo account di servizio. Per includere l’utilizzo senza chiave API in un filtro `api_key_ids[]`, aggiungi una voce vuota: `api_key_ids[]=`. I filtri `api_key_ids[]` e `actor_ids[]` rispondono a domande diverse. `api_key_ids[]=apikey_...` corrisponde a ogni richiesta autenticata dalla chiave, indipendentemente da a chi sia attribuita. `actor_ids[]=apikey_...` corrisponde solo alle richieste attribuite alla chiave stessa. ## Endpoint di utilizzo `GET /v1/organizations/analytics/usage` restituisce i conteggi dei token per tipo. `order_by` accetta `total_tokens` (il valore predefinito), `output_tokens`, `uncached_input_tokens`, `requests` o `time`. Ad esempio, per vedere una settimana di utilizzo per un workspace e una chiave API, suddivisa per livello di servizio (una riga per ciascun livello, che copre l’intera settimana): ```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 ``` Per cercare gli ID delle chiavi API e dei workspace, usa gli endpoint [List API Keys](https://platform.claude.com/docs/it/api/organization/api_keys/list) e [List Workspaces](https://platform.claude.com/docs/it/api/organization/workspaces/list) oppure la Claude Console. Per trovare quali utenti, account di servizio e chiavi API hanno effettuato più richieste in un mese: ```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 dei costi `GET /v1/organizations/analytics/cost` accetta gli stessi filtri, dimensioni e intervalli temporali dell’endpoint `/usage`. L’oggetto `cost` di ogni riga contiene `amount` (il costo dopo gli sconti e prima dell’applicazione di eventuali crediti), `list_amount` (il costo a prezzi di listino), `currency` (sempre `"USD"`) e `requests`. Gli importi sono stringhe decimali in centesimi con sei cifre decimali: `"41280.000000"` corrisponde a $412,80 USD. `order_by` accetta `amount` (il valore predefinito), `list_amount` o `time`. Due dimensioni aggiuntive esistono solo in questo endpoint e non contano ai fini del limite di cinque dimensioni: `group_by[]=cost_type` suddivide ogni riga in una riga per ciascun tipo di costo, e `group_by[]=token_type` suddivide il costo dei token in una riga per ciascun tipo di token. Nemmeno `limit` si applica a queste due dimensioni, quindi una pagina può contenere più di `limit` righe. Ad esempio, il costo per modello, tipo di costo e tipo di token per un mese: ```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 ``` Per ciascun modello, la risposta contiene cinque righe `tokens` (una per ciascun tipo di token) più una riga ciascuna per `web_search`, `code_execution` e `session_usage`. Una di queste righe: ```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 } } ``` L’oggetto `group` contiene tutte le dimensioni ed è abbreviato qui. Quando è specificato `group_by[]=cost_type` o `token_type`, `requests` è `null` in ogni riga. Le richieste servite nell’ambito di un impegno Priority Tier compaiono nell’endpoint di utilizzo con `service_tier: "priority"` ma contribuiscono con un costo dei token pari a zero ad `amount` e `list_amount`, perché il tuo impegno le copre; la tariffa dell’impegno viene fatturata separatamente e non è inclusa in questi dati. La ricerca web su queste richieste viene fatturata alla tariffa standard. Le richieste che superano la capacità impegnata vengono servite e tariffate al livello standard. ## Intervalli di date e intervalli temporali * I timestamp sono in formato RFC 3339 con un offset UTC, ad esempio `2026-09-01T00:00:00Z`. `starting_at` è inclusivo e `ending_at` è esclusivo. * `starting_at` deve essere uguale o successivo al 1° gennaio 2026 e compreso negli ultimi 365 giorni. Una richiesta può coprire al massimo 31 giorni; per impostazione predefinita, `ending_at` corrisponde a 31 giorni dopo `starting_at` o all’ora corrente, a seconda di quale sia precedente. * `ending_at` è obbligatorio ogni volta che è impostato `time_bucket_width`, e con `time_bucket_width=1m` una richiesta può coprire al massimo 24 ore. * Entrambi gli estremi dell’intervallo vengono arrotondati per difetto al limite di un intervallo UTC, o all’ora quando `time_bucket_width` non è impostato. Ad esempio, con `time_bucket_width=1h`, uno `starting_at` di `2026-09-01T10:43:00Z` viene trattato come `2026-09-01T10:00:00Z` e un `ending_at` di `2026-09-01T15:43:00Z` come `2026-09-01T15:00:00Z`, quindi la risposta copre dalle 10:00 alle 15:00 UTC. ## Aggiornamento dei dati Ogni risposta include un timestamp `data_refreshed_at`, e l’utilizzo successivo a quel momento è mancante o parziale. Quando non sono ancora disponibili dati per nessuna parte dell’intervallo richiesto, `data_refreshed_at` è `null` e `data` è vuoto. I dati vengono in genere aggiornati entro 4 ore dall’utilizzo sottostante e possono richiedere fino a 24 ore. I valori possono essere rivisti man mano che arrivano eventi in ritardo e vengono eseguite le riconciliazioni, fino a circa 7 giorni dopo la fine del mese solare. Ad esempio, i valori del 1° ottobre possono cambiare fino a circa il 7 novembre. Per ottenere risultati stabili tra chiamate ripetute, imposta `ending_at` a un valore uguale o precedente a un `data_refreshed_at` che hai già visto; per i totali definitivi, interroga solo i mesi terminati da almeno 7 giorni. Ogni pagina di una query paginata legge la stessa istantanea dei dati, quindi `data_refreshed_at` è identico tra le pagine. ## Migrare dall’API Usage and Cost Questa sezione è rivolta alle organizzazioni Claude Console che chiamano l’[API Usage and Cost](https://platform.claude.com/docs/it/manage-claude/usage-cost-api) legacy (`/v1/organizations/usage_report/messages` e `/v1/organizations/cost_report`). La tua chiave Admin API, l’header `anthropic-version`, `starting_at` e `ending_at`, i valori di ampiezza degli intervalli (`1m`, `1h`, `1d`), la notazione con parentesi quadre, i nomi dei campi di paginazione e i nomi dei campi di token e costo restano invariati. Cosa cambia: | API Usage and Cost | API Usage and Cost Analytics | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Nessun header beta | `anthropic-beta: analytics-usage-cost-2026-08-24` in ogni richiesta | | I dati compaiono in genere entro 5 minuti | I dati vengono in genere aggiornati entro 4 ore e possono richiedere fino a 24 ore (vedi [Aggiornamento dei dati](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#data-freshness)) | | `data` è una lista di intervalli temporali, dal più vecchio, inclusi quelli vuoti, ciascuno con una lista `results` le cui voci contengono dimensioni e metriche affiancate | `data` è una lista di righe ordinate per `order_by`, ciascuna con i propri `starting_at` e `ending_at`, le dimensioni in `group` e le metriche in `usage` o `cost`. Le combinazioni senza utilizzo o costo non hanno righe. | | `bucket_width`, predefinito `1d` | `time_bucket_width`, nessun valore predefinito. Passa `time_bucket_width=1d` per mantenere le righe giornaliere; omettilo per i totali sull’intero intervallo. L’endpoint dei costi accetta anche tutti i filtri e gli intervalli `1m` e `1h`. | | `limit` conta gli intervalli temporali per pagina | `limit` conta le righe per pagina (da 1 a 1.000, predefinito 20), quindi il numero di pagine dipende da quante combinazioni hanno dati | | Qualsiasi intervallo di date, paginato in avanti per intervallo | `starting_at` a partire dal 1° gennaio 2026 ed entro gli ultimi 365 giorni, al massimo 31 giorni per richiesta, `ending_at` obbligatorio con `time_bucket_width` e al massimo 24 ore con intervalli `1m` (vedi [Intervalli di date e intervalli temporali](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#date-ranges-and-time-buckets)). Suddividi gli intervalli più lunghi in più richieste. | | `account_ids[]`, `service_account_ids[]`, `group_by[]=account_id`, `group_by[]=service_account_id` | `actor_ids[]` con gli stessi ID con prefisso, e `group_by[]=actor` o `actor_type`; leggi `actor.user_id` o `actor.service_account_id`. Vedi [Attori](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#actors). | | `context_window[]` | `context_windows[]` | | `group_by[]=description` nel report dei costi, con una stringa `description` | Nessun `description`. Raggruppa invece per le dimensioni strutturate: qualsiasi tra `model`, `cost_type`, `token_type`, `context_window`, `service_tier`, `inference_geo` e `speed`, che rientrano tutte in una sola richiesta. | | Un ID di chiave API o di workspace sconosciuto restituisce un errore | Non corrisponde a nulla, incluso un nome `models[]` scritto in modo errato. Ogni lista accetta fino a 100 valori. | | `workspace_id: null` per il workspace predefinito | Il `workspace_id` reale del workspace predefinito (vedi [Come viene rappresentato il workspace predefinito?](https://platform.claude.com/docs/it/manage-claude/usage-cost-analytics-api#how-is-the-default-workspace-represented)) | | `inference_geo: "not_available"` e `service_tier: "standard"` sull’utilizzo senza area geografica o livello | `null` per entrambi. `inference_geos[]=not_available` corrisponde comunque alle righe senza area geografica di inferenza. | | Il `service_tier` dei costi è `standard` o `batch`; `amount` come `"123.45"` | Il livello effettivo; `amount` con sei cifre decimali, come `"123.450000"`, più `list_amount`. | | Esecuzione di codice non presente nel report di utilizzo; nessun conteggio delle richieste | L’esecuzione di codice compare come righe di utilizzo con `model: null`; aggiunge `requests` in entrambi gli endpoint e `total_tokens` nelle righe di utilizzo | Per riprodurre il report giornaliero legacy, richiedi `time_bucket_width=1d` con lo stesso `group_by[]`, scorri le pagine con `limit=1000`, quindi raggruppa le righe per `starting_at` e riempi i giorni mancanti con zeri. Aggiungi `order_by=time&order=asc` per ottenere i giorni in ordine. Utilizzo giornaliero per modello per 1 settimana, prima: ```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 dopo: ```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 ``` Costo giornaliero per workspace, modello, livello di servizio, finestra di contesto e area geografica di inferenza, suddiviso per tipo di costo e tipo di 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 ``` ## Migrare dai report di utilizzo e costo di Claude Enterprise Questa sezione è rivolta alle organizzazioni Claude Enterprise che chiamano gli endpoint di report della [Claude Enterprise Analytics API](https://platform.claude.com/docs/it/manage-claude/analytics-api) `usage_report`, `cost_report`, `user_usage_report` e `user_cost_report` sotto `/v1/organizations/analytics/`. Questi endpoint sono legacy e restano supportati. Passa a `/analytics/usage` e `/analytics/cost` quando desideri una delle seguenti funzionalità: * Ogni gruppo in ogni intervallo temporale, anziché i primi 100 gruppi di ciascun intervallo * Raggruppamento per `actor` o `actor_type` insieme ad altre dimensioni, sia per l’utilizzo sia per i costi * Righe ordinate in base a una metrica a tua scelta sull’intero intervallo, oppure ordinate per intervallo temporale * Un’unica integrazione che serve anche le organizzazioni Claude Console La tua chiave, la data più remota, il periodo di 365 giorni a ritroso e l’arco di 31 giorni, i nomi e i valori dei filtri e delle dimensioni (eccetto `user_ids[]` e il valore di prodotto Claude Tag), i campi `actor` dell’utente, i campi delle metriche e degli importi, `data_refreshed_at`, le regole del cursore e il [limite di velocità a livello di organizzazione](https://platform.claude.com/docs/it/manage-claude/analytics-api#working-with-the-api) restano invariati. L’unico nuovo header è l’header beta `analytics-usage-cost-2026-08-24`. Cosa cambia: | Report di Claude Enterprise | API Usage and Cost Analytics | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `usage_report` e `cost_report` restituiscono intervalli temporali, dal più vecchio, inclusi quelli vuoti, ciascuno contenente al massimo i suoi primi 100 gruppi; `bucket_width` è predefinito a `1d` e `limit` conta gli intervalli | Righe che coprono ogni combinazione con dati, ordinate per `order_by`, ciascuna con i propri `starting_at` e `ending_at`, le dimensioni in `group` e le metriche in `usage` o `cost`. `time_bucket_width` è facoltativo e `limit` conta le righe. | | Il parametro dell’intervallo temporale è `bucket_width` | È `time_bucket_width`, con gli stessi valori | | In `usage_report` e `cost_report`, `ending_at` è facoltativo con `bucket_width` e gli intervalli `1m` possono coprire fino a 31 giorni | `ending_at` obbligatorio con `time_bucket_width`; gli intervalli `1m` coprono al massimo 24 ore per richiesta | | `user_usage_report` e `user_cost_report` restituiscono una riga per utente | `group_by[]=actor&actor_types[]=user_actor`. Senza il filtro ottieni anche righe per identità non utente e una riga `actor: null` per l’utilizzo non attribuito. | | L’utilizzo di Claude Tag ha `product: "claude-tag"` | `product: "claude_tag"`; `products[]` accetta entrambe le grafie | | Un nome `models[]` non riconosciuto restituisce un errore 400 | Non corrisponde a nulla | | `user_ids[]` | `actor_ids[]` con gli stessi ID con prefisso `user_...` | | `exclude_deleted_users` nei report per utente | Richiede `group_by[]=actor`; senza di esso, la richiesta restituisce un errore 400. Esclude solo le righe il cui `actor` è un utente con `deleted: true`; le righe per altre identità e le righe con `actor: null` restano. | Costo per utente per un mese, prima: ```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 dopo, aggiungendo una suddivisione per prodotto: ```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 ``` ## Domande frequenti ### Come viene rappresentato il workspace predefinito? Il workspace predefinito di un’organizzazione Claude Console ha un proprio ID `wrkspc_`, come ogni altro workspace. Le righe del workspace predefinito hanno quell’ID in `workspace_id`, e puoi filtrare in base a esso con `workspace_ids[]`. [List Workspaces](https://platform.claude.com/docs/it/api/organization/workspaces/list) esclude il workspace predefinito a meno che tu non passi `include_default=true`. Per verificare se un `workspace_id` sconosciuto è il workspace predefinito, passalo a [Get Workspace](https://platform.claude.com/docs/it/api/organization/workspaces/retrieve): il workspace predefinito restituisce `"name": "Default"`. ### Come ottengo il costo per utente per Claude Code? Chiama l’endpoint dei costi con `products[]=claude_code&group_by[]=actor`. Le organizzazioni Claude Console possono anche usare la [Claude Code Analytics API](https://platform.claude.com/docs/it/manage-claude/claude-code-analytics-api), che riporta l’attività di Claude Code per utente e il costo stimato. ## Vedi anche * [API Usage and Cost](https://platform.claude.com/docs/it/manage-claude/usage-cost-api) (legacy) * [API di analisi](https://platform.claude.com/docs/it/manage-claude/analytics-api): quale API di analisi e quale tipo di chiave servono alla tua organizzazione * [Claude Code Analytics API](https://platform.claude.com/docs/it/manage-claude/claude-code-analytics-api) * [Riferimento Admin API](https://platform.claude.com/docs/it/api/beta/organization) * [Prezzi](https://platform.claude.com/docs/it/about-claude/pricing)