> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude API traces

> Send OpenTelemetry traces from the Claude API and the Claude SDK to Squasher, and see each request, model run, tool use, and Managed Agents session.

The Claude API and the Claude SDKs emit OpenTelemetry spans for each Messages API request, model
run, tool use, and Managed Agents session. Send them to Squasher to see their tokens, cost,
latency, and status in [AI observability](/features/ai-observability), next to your own traces.

| Source | What it adds | Setup |
| - | - | - |
| Claude API | A span for each request, each model run, each server or MCP tool use, and each Managed Agents turn. | A destination in Console |
| Claude SDK | A span for each request that your app sends, and for each tool that the tool runner runs. | A tracer provider in code |

You can use one source or both. Squasher counts the tokens and cost of a request once, also when
both sources send spans for it.

## What you need

* The admin role in your Claude Console organization, to add a destination.
* A Squasher ingest key in `SQUASHER_API_KEY`. See
  [Create an ingest key](/quickstart#create-an-ingest-key).

## Send Claude API spans

<Steps>
  <Step title="Add a destination">
    In the Claude Console, open the OpenTelemetry settings page and select **Add destination**.

    | Field | Value |
    | - | - |
    | Provider | **Custom** |
    | OTLP endpoint URL | `https://ingest.squasher.ai` |
    | Request headers | `x-squasher-key` with your ingest key |
    | Content mode | **Metadata only** or **Full content** |
    | Workspaces | The workspaces that you want to trace |

    Do not add `/v1/traces` to the URL. The Claude API adds it.
  </Step>

  <Step title="Test the destination">
    Select **Test** in the destination's **More actions** menu. Squasher stores an `anthropic.test`
    span. Select **Logs** in the sidebar, choose **Traces**, and filter on
    `service.name:claude-platform`.
  </Step>
</Steps>

To add the destination with the Admin API instead:

```bash theme={null}
curl -sS "https://api.anthropic.com/v1/organizations/telemetry_destinations" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: telemetry-destinations-2026-08-11" \
  -H "content-type: application/json" \
  -d '{
    "endpoint_url": "https://ingest.squasher.ai",
    "headers": {"x-squasher-key": "'"$SQUASHER_API_KEY"'"},
    "traces": {"content_mode": "metadata_only"},
    "workspaces": {"type": "all"}
  }'
```

**Full content** adds prompts, responses, tool arguments, and tool results to the spans. Squasher
shows them on the request page. The default content limit of 0.75 MB for each span is in the
Squasher limit of 16 MiB for each request.

## Send Claude SDK spans

The Claude SDK writes its spans to the tracer provider of your app. Export them over OTLP/HTTP with
the variables from [OpenTelemetry](/integrations/opentelemetry#set-the-exporter-variables):

```bash theme={null}
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.squasher.ai
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="x-squasher-key=$SQUASHER_API_KEY"
```

The SDK sends the trace context with each request. When the Claude API destination is also on, the
API spans of a request appear under its SDK span in the same trace.

## Read Claude data in Squasher

* **Requests**: each `anthropic.messages.create` span, each `anthropic.model_request`, and each
  `anthropic.compaction` is a model call. The trace shows the SDK span over the API span over the
  model runs.
* **Tokens and cost**: Squasher counts the deepest span that reports usage, so a request counts
  once. Cache reads and writes are part of the input tokens. Cache writes with a 1-hour lifetime
  use twice the input price.
* **Sessions**: a Managed Agents session groups by `anthropic.session.id`, across all of its
  traces and threads. A Messages API conversation groups by `gen_ai.conversation.id`, which you
  set with the SDK's `conversation_id` option.
* **Agents**: turns show the agent from `gen_ai.agent.id`.
* **Needs attention**: Squasher reads the stop reason (`anthropic.message.stop_reason`) and the
  error type, such as `rate_limit_error` or `overloaded_error`.

## Limits

* The Claude API delivers spans at least once. Squasher counts each span once by its trace ID and
  span ID.
* Spans count toward the project limit of records per minute. A `429` response makes the Claude
  API retry the delivery later.
* The Claude API does not trace requests on the OpenAI-compatible endpoint.

## Next steps

<CardGroup cols={2}>
  <Card title="AI observability" icon="https://mintcdn.com/nextbigthingllc/Fg5aclMlZNSrg_Y3/icons/nav/ai.svg?fit=max&auto=format&n=Fg5aclMlZNSrg_Y3&q=85&s=80600b989a9dd0ceccb393b489fc7e51" href="/features/ai-observability" width="24" height="24" data-path="icons/nav/ai.svg">
    Find slow or failing calls and follow one agent run.
  </Card>

  <Card title="OpenTelemetry" icon="https://mintcdn.com/nextbigthingllc/e12gFqmgX0x4CiVm/icons/brands/opentelemetry.svg?fit=max&auto=format&n=e12gFqmgX0x4CiVm&q=85&s=fb5ec167b8e372d6e298b589c6f1f5d4" href="/integrations/opentelemetry" width="1024" height="1024" data-path="icons/brands/opentelemetry.svg">
    Endpoint, headers, and limits for OTLP/HTTP.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.