Programmatically access your organization's API usage and cost data with the Usage & Cost Admin API. The Usage API tracks token consumption with breakdowns by model, workspace, and service tier via /v1/organizations/usage_report/messages. The Cost API retrieves service-level USD breakdowns via /v1/organizations/cost_report. Requires an Admin API key.
openapi: 3.1.0
info:
title: Anthropic Usage and Cost API
description: >
Programmatically access your organization's API usage and cost data via
the Usage & Cost Admin API. The Usage API tracks token consumption across
your organization with breakdowns by model, workspace, and service tier.
The Cost API retrieves service-level cost breakdowns in USD. Both
endpoints require an Admin API key (sk-ant-admin...).
version: 2023-06-01
contact:
name: Anthropic Support
url: https://support.claude.com
license:
name: Anthropic Terms of Service
url: https://www.anthropic.com/terms
servers:
- url: https://api.anthropic.com
description: Production Server
security:
- AdminApiKeyAuth: []
tags:
- name: Usage
description: Token usage and consumption reporting
- name: Cost
description: Service-level cost reporting
paths:
/v1/organizations/usage_report/messages:
get:
summary: Anthropic Get Messages Usage Report
description: >
Aggregated token usage for Messages API requests, broken down by
day, model, workspace, and service tier.
operationId: getMessagesUsageReport
tags:
- Usage
parameters:
- $ref: '#/components/parameters/AnthropicVersion'
- $ref: '#/components/parameters/StartingAt'
- $ref: '#/components/parameters/EndingAt'
- $ref: '#/components/parameters/Bucket'
- $ref: '#/components/parameters/GroupBy'
- $ref: '#/components/parameters/Models'
- $ref: '#/components/parameters/WorkspaceIds'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Usage report.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageReport'
'4XX':
$ref: '#/components/responses/ErrorResponse'
/v1/organizations/cost_report:
get:
summary: Anthropic Get Cost Report
description: >
Service-level cost breakdowns for the organization in USD, including
Messages, Batches, Files, Skills, and Claude Code line items.
operationId: getCostReport
tags:
- Cost
parameters:
- $ref: '#/components/parameters/AnthropicVersion'
- $ref: '#/components/parameters/StartingAt'
- $ref: '#/components/parameters/EndingAt'
- $ref: '#/components/parameters/Bucket'
- $ref: '#/components/parameters/GroupBy'
- $ref: '#/components/parameters/WorkspaceIds'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Cost report.
content:
application/json:
schema:
$ref: '#/components/schemas/CostReport'
'4XX':
$ref: '#/components/responses/ErrorResponse'
components:
securitySchemes:
AdminApiKeyAuth:
type: apiKey
in: header
name: x-api-key
parameters:
AnthropicVersion:
name: anthropic-version
in: header
required: true
schema:
type: string
default: "2023-06-01"
StartingAt:
name: starting_at
in: query
required: true
description: RFC3339 inclusive lower bound for the report window.
schema:
type: string
format: date-time
EndingAt:
name: ending_at
in: query
required: false
description: RFC3339 exclusive upper bound for the report window.
schema:
type: string
format: date-time
Bucket:
name: bucket_width
in: query
required: false
description: Aggregation bucket size.
schema:
type: string
enum:
- 1h
- 1d
default: 1d
GroupBy:
name: group_by
in: query
required: false
description: Dimensions to group the report by.
explode: true
schema:
type: array
items:
type: string
enum:
- workspace_id
- api_key_id
- model
- service_tier
- context_window
Models:
name: models
in: query
required: false
explode: true
schema:
type: array
items:
type: string
WorkspaceIds:
name: workspace_ids
in: query
required: false
explode: true
schema:
type: array
items:
type: string
Limit:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 20
Page:
name: page
in: query
required: false
schema:
type: string
schemas:
UsageReport:
type: object
properties:
data:
type: array
items:
type: object
properties:
starting_at:
type: string
format: date-time
ending_at:
type: string
format: date-time
results:
type: array
items:
type: object
properties:
workspace_id:
type: string
nullable: true
api_key_id:
type: string
nullable: true
model:
type: string
nullable: true
service_tier:
type: string
nullable: true
context_window:
type: string
nullable: true
uncached_input_tokens:
type: integer
cache_read_input_tokens:
type: integer
cache_creation_5m_input_tokens:
type: integer
cache_creation_1h_input_tokens:
type: integer
output_tokens:
type: integer
server_tool_use:
type: object
has_more:
type: boolean
next_page:
type: string
nullable: true
CostReport:
type: object
properties:
data:
type: array
items:
type: object
properties:
starting_at:
type: string
format: date-time
ending_at:
type: string
format: date-time
results:
type: array
items:
type: object
properties:
workspace_id:
type: string
nullable: true
description:
type: string
cost_type:
type: string
context_window:
type: string
nullable: true
model:
type: string
nullable: true
service_tier:
type: string
nullable: true
token_type:
type: string
nullable: true
currency:
type: string
default: USD
amount:
type: string
has_more:
type: boolean
next_page:
type: string
nullable: true
Error:
type: object
properties:
type:
type: string
error:
type: object
properties:
type:
type: string
message:
type: string
responses:
ErrorResponse:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'