> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Claude as a data source
> Bring Claude usage and cost data to Nekt.
Claude (Anthropic) provides usage reporting and cost breakdowns for your organizations and API keys. This connector extracts those reports from the Anthropic Admin API and lands them in your Nekt Catalog as queryable tables.
This connector is not available for individual Claude accounts, only organization ones.
## Configuring Claude as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Claude option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need an Anthropic Admin API key with access to usage and cost reporting for your organization. Once you have it, add the account access, then click **Next**.
The following configurations are available:
* **Admin API Key**: Anthropic Admin API key (starts with `sk-ant-admin...`).
* **Start Date**: Select the earliest date you want to extract data from.
Make sure the API key you use has the required Admin permissions for usage and cost reporting. Without it, the connector cannot extract data from the Anthropic Admin API.
### 2. Select streams
Choose which data streams you want to sync:
* **Messages Usage**: Token usage report (grouped by model, workspace, API key, service tier, and context window).
* **Cost Report**: Cost breakdown report (grouped by workspace and cost-item description).
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table and the type of sync.
* **Layer**: choose between the existing layers on your catalog.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You can add a **prefix** to all tables at once.
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: only new/updated buckets since the last successful run are extracted.
* Full table: every run fetches the full current state of the selected stream.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated.
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Claude and their corresponding fields:
Token usage report grouped by model, workspace, API key, service tier, and context window.
| Field | Type | Description |
| :----------------------------------------- | :------- | :---------------------------------------------------------- |
| `starting_at` | DateTime | Start of the time bucket. |
| `ending_at` | DateTime | End of the time bucket. |
| `model` | String | Model used. |
| `workspace_id` | String | Workspace ID. |
| `api_key_id` | String | API key ID. |
| `service_tier` | String | Service tier (for example, standard, batch, priority). |
| `context_window` | String | Context window bucket (for example, `0-200k` or `200k-1M`). |
| `uncached_input_tokens` | Integer | Uncached input tokens. |
| `cache_read_input_tokens` | Integer | Tokens read from cache. |
| `cache_creation_ephemeral_5m_input_tokens` | Integer | Tokens for 5-minute cache creation. |
| `cache_creation_ephemeral_1h_input_tokens` | Integer | Tokens for 1-hour cache creation. |
| `output_tokens` | Integer | Output tokens generated. |
| `web_search_requests` | Integer | Number of web search requests. |
Cost breakdown grouped by workspace and cost-item description (which includes model and token type).
| Field | Type | Description |
| :--------------- | :------- | :---------------------------------------------------------- |
| `starting_at` | DateTime | Start of the time bucket. |
| `ending_at` | DateTime | End of the time bucket. |
| `workspace_id` | String | Workspace ID. |
| `description` | String | Cost item description. |
| `amount` | String | Cost amount in cents (USD). |
| `currency` | String | Currency code (USD). |
| `cost_type` | String | Cost type (tokens, web\_search, or code\_execution). |
| `model` | String | Model name. |
| `token_type` | String | Token type (uncached\_input\_tokens, output\_tokens, etc.). |
| `service_tier` | String | Service tier (standard or batch). |
| `context_window` | String | Context window bucket (for example, `0-200k` or `200k-1M`). |
| `inference_geo` | String | Inference geography. |
The connector uses daily time buckets (`bucket_width = 1d`) and uses `starting_at` as the replication key for incremental sync.
## Use Cases for Data Analysis
This guide outlines a couple of common business intelligence use cases when consolidating Claude usage and cost data in your Catalog.
### 1. Token usage by model
Analyze how input/output tokens and web search activity vary by model over time.
```sql theme={null}
SELECT
model,
context_window,
SUM(uncached_input_tokens) AS uncached_input_tokens,
SUM(cache_read_input_tokens) AS cache_read_input_tokens,
SUM(cache_creation_ephemeral_5m_input_tokens) AS cache_creation_ephemeral_5m_input_tokens,
SUM(cache_creation_ephemeral_1h_input_tokens) AS cache_creation_ephemeral_1h_input_tokens,
SUM(output_tokens) AS output_tokens,
SUM(web_search_requests) AS web_search_requests
FROM
nekt_raw.claude_messages_usage
WHERE
starting_at >= current_timestamp - interval '30' day
GROUP BY
model,
context_window
ORDER BY
output_tokens DESC
```
```sql theme={null}
SELECT
model,
context_window,
SUM(uncached_input_tokens) AS uncached_input_tokens,
SUM(cache_read_input_tokens) AS cache_read_input_tokens,
SUM(cache_creation_ephemeral_5m_input_tokens) AS cache_creation_ephemeral_5m_input_tokens,
SUM(cache_creation_ephemeral_1h_input_tokens) AS cache_creation_ephemeral_1h_input_tokens,
SUM(output_tokens) AS output_tokens,
SUM(web_search_requests) AS web_search_requests
FROM
`nekt_raw.claude_messages_usage`
WHERE
starting_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY
model,
context_window
ORDER BY
output_tokens DESC
```
| model | context\_window | uncached\_input\_tokens | cache\_read\_input\_tokens | output\_tokens | web\_search\_requests |
| ----------------- | --------------: | ----------------------: | -------------------------: | -------------: | --------------------: |
| claude-3-5-sonnet | 0-200k | 12,450,000 | 3,210,000 | 8,930,000 | 42,810 |
| claude-3-opus | 200k-1M | 7,110,000 | 1,905,000 | 4,620,000 | 18,120 |
### 2. Cost breakdown by token type
Understand which token categories dominate spend.
```sql theme={null}
SELECT
cost_type,
model,
token_type,
SUM(CAST(amount AS DOUBLE)) / 100.0 AS cost_usd
FROM
nekt_raw.claude_cost_report
WHERE
starting_at >= current_timestamp - interval '30' day
AND cost_type = 'tokens'
GROUP BY
cost_type,
model,
token_type
ORDER BY
cost_usd DESC
```
```sql theme={null}
SELECT
cost_type,
model,
token_type,
SUM(CAST(amount AS FLOAT64)) / 100.0 AS cost_usd
FROM
`nekt_raw.claude_cost_report`
WHERE
starting_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
AND cost_type = 'tokens'
GROUP BY
cost_type,
model,
token_type
ORDER BY
cost_usd DESC
```
| cost\_type | model | token\_type | cost\_usd |
| ---------- | ----------------- | ----------------------- | ---------: |
| tokens | claude-3-5-sonnet | output\_tokens | 124,531.20 |
| tokens | claude-3-5-sonnet | uncached\_input\_tokens | 88,102.77 |
| tokens | claude-3-opus | output\_tokens | 41,009.65 |
## Implementation Notes
The connector authenticates against the Anthropic Admin API using `admin_api_key` as the `x-api-key` request header.
Reports are fetched using daily buckets (`bucket_width = 1d`) and paginated through the Admin API using a `page` cursor when the response indicates more results.
Anthropic Admin API calls are rate-limited conservatively (shared limit of 1 call per 4 seconds) and retried using exponential backoff (up to 12 retries). The connector automatically handles HTTP 429 rate limit responses by respecting the `Retry-After` header when provided by the API, helping prevent transient failures during large backfills.
`cost_report.amount` is returned as a string representing cents (USD). Divide by `100` to get the value in USD.
## Skills for agents
Claude connector documentation as plain markdown, for use in AI agent contexts.