# Pi AI Telemetry Schema

<!-- Generated by generate-telemetry-docs.ts. Do not edit manually. -->

Schema version: 1

## `pi.ai.request`

One logical request to an AI provider

- Parents: root or any caller span
- Default status: `ok`
- Error when: The operation throws or returns an error result

### Start attributes

| Name | Type | Required | Values | Notes | Description |
|---|---|---:|---|---|---|
| `pi.ai.operation` | `string` | yes | stream, fetch_deferred, cancel_deferred, generate_images |  | Logical provider operation |
| `pi.ai.provider` | `string` | yes |  |  | Selected provider id |
| `pi.ai.model` | `string` | yes |  |  | Requested model id |
| `pi.ai.api` | `string` | yes |  |  | Provider API id |
| `pi.ai.streaming` | `boolean` | yes |  |  | Whether this operation returns a stream |
| `pi.ai.deferred` | `boolean` | no |  |  | Whether the operation requests or participates in deferred execution |

### End attributes

All end attributes are optional completion enrichment.

| Name | Type | Values | Notes | Description |
|---|---|---|---|---|
| `pi.ai.response.model` | `string` |  |  | Concrete response model |
| `pi.ai.response.id` | `string` |  | high cardinality | Provider response id |
| `pi.ai.response.stop_reason` | `string` | stop, length, tool_use, error, aborted, deferred |  | Normalized terminal response reason |
| `pi.ai.http.status_code` | `number` |  |  | Final HTTP status |
| `pi.ai.usage.input_tokens` | `number` |  |  | Reported input tokens |
| `pi.ai.usage.output_tokens` | `number` |  |  | Reported output tokens |
| `pi.ai.usage.cache_read_tokens` | `number` |  |  | Reported cache-read tokens |
| `pi.ai.usage.cache_write_tokens` | `number` |  |  | Reported cache-write tokens |
| `pi.ai.usage.reasoning_tokens` | `number` |  |  | Reported reasoning tokens |
| `pi.ai.usage.total_tokens` | `number` |  |  | Reported total tokens |
| `pi.ai.usage.cost` | `number` |  |  | Reported total cost |
| `pi.ai.stream.chunk_count` | `number` |  |  | Streamed update chunk count |
| `pi.ai.stream.time_to_first_chunk_ms` | `number` |  |  | Elapsed milliseconds to first update chunk |
| `pi.ai.error.type` | `string` |  | low cardinality | Provider or transport error class |

### Events

No declared span events.