# API reference

Agents talk to the gateway over gRPC with mutual TLS on port 4317, using the `IngestionService` in package `observability.v1`. The SDKs wrap this API. Use it directly only if you're writing a client in another language. This page is generated from the `.proto` files and the gateway's validation constants, so it always matches the code.

## Authentication and identity

Every RPC requires a TLS 1.3 client certificate signed by the CA the gateway trusts. The certificate's CommonName is the agent's identity. The gateway stamps it on every span (`agent_name`), log (`agent_name`) and metric (`agent` label), overwriting any value the client supplies.

## Errors and partial acceptance

- **`IngestSpan`** returns `accepted: false` with a `rejection_reason` when validation fails.
- **`IngestBatch`** validates each item independently. It returns per-kind accepted counts, plus an `errors` list with entries like `log[2]: validation: log body is required`, where the index is the item's position in its kind's list.
- **gRPC status `RESOURCE_EXHAUSTED`:** the agent is over its rate limit (charged per item). Retry later.
- **gRPC status `INVALID_ARGUMENT`:** the batch is larger than 1000 items or the per-agent limit; split it.
- **gRPC status `UNAUTHENTICATED`:** no valid client certificate.

## Ingestion limits

| Applies to | Field | Rule |
|---|---|---|
| Span | `trace_id`, `span_id`, `parent_id` | 1–64 characters of `[A-Za-z0-9_-]` (`parent_id` may be empty). SDKs send W3C sizes: 32 and 16 hex characters. |
| Span | `name` | Required, at most 256 bytes |
| Span | duration | `end_time` ≥ `start_time`, at most 24 hours |
| Span, log | `attributes` | At most 128 entries; keys 1–128 bytes; values at most 4 KiB |
| Span | `llm_call.prompt` / `completion` | At most 128 KiB each (dropped at the gateway when `STORE_LLM_PAYLOADS=false`) |
| Span | `llm_call.model` | At most 256 bytes |
| Span | `llm_call` tokens and cost | Token counts ≥ 0; `cost_usd` finite and ≥ 0 |
| Log | `body` | Required, at most 32 KiB |
| Log, metric | `timestamp` | No more than 1 hour in the future; the receive time if unset |
| Log | `trace_id` / `span_id` | Optional, same format as spans; `span_id` requires `trace_id` |
| Metric | `name` | Prometheus name `[a-zA-Z_:][a-zA-Z0-9_:]*`, at most 200 characters; `conduit_*` and `__*` are reserved |
| Metric | `labels` | At most 32; keys `[a-zA-Z_][a-zA-Z0-9_]*` (at most 128, not `__*`); values at most 1 KiB. The `agent` label is always set by the gateway. |
| Metric | `value` | Finite; counters ≥ 0 |
| Batch | items per `IngestBatch` | At most 1000 (spans + metrics + logs), and no more than the per-agent rate limit (`RATE_LIMIT_RPS`) |

## `ingestion.proto`

### service `IngestionService`

IngestionService is the gateway's inbound API. All RPCs require mTLS — agent identity comes from the client certificate.

| RPC | Request | Response | Description |
|---|---|---|---|
| `IngestSpan` | `IngestSpanRequest` | `IngestSpanResponse` | IngestSpan submits a single span. Used for real-time streaming from agents. |
| `IngestBatch` | `IngestBatchRequest` | `IngestBatchResponse` | IngestBatch submits spans, metrics, and logs. Each item is validated and accepted independently (not atomically); rejected items are reported in IngestBatchResponse.errors. |

### message `IngestSpanRequest`

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `span` | `Span` |  |

### message `IngestSpanResponse`

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `accepted` | `bool` |  |
| 2 | `rejection_reason` | `string` | set if accepted=false |

### message `IngestBatchRequest`

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `spans` | `repeated Span` |  |
| 2 | `metrics` | `repeated Metric` |  |
| 3 | `logs` | `repeated LogRecord` |  |

### message `IngestBatchResponse`

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `spans_accepted` | `int32` |  |
| 2 | `metrics_accepted` | `int32` |  |
| 3 | `logs_accepted` | `int32` |  |
| 4 | `errors` | `repeated string` | one per rejected item, e.g. "log[2]: validation: ..." |

## `span.proto`

### message `Span`

Span represents a single unit of work in an agent execution trace.

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `trace_id` | `string` |  |
| 2 | `span_id` | `string` |  |
| 3 | `parent_id` | `string` | empty if root span |
| 4 | `name` | `string` |  |
| 5 | `start_time` | `google.protobuf.Timestamp` |  |
| 6 | `end_time` | `google.protobuf.Timestamp` |  |
| 7 | `status` | `SpanStatus` |  |
| 8 | `attributes` | `map<string, string>` |  |
| 9 | `llm_call` | `LLMCallData` | Optional — set only for LLM call spans |

### enum `SpanStatus`

| Value | Number | Description |
|---|---|---|
| `SPAN_STATUS_UNSET` | 0 |  |
| `SPAN_STATUS_OK` | 1 |  |
| `SPAN_STATUS_ERROR` | 2 |  |

### message `LLMCallData`

LLMCallData captures the full context of a single inference call. Stored separately from span metadata to allow payload-level access control.

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `model` | `string` |  |
| 2 | `prompt` | `string` |  |
| 3 | `completion` | `string` |  |
| 4 | `input_tokens` | `int32` |  |
| 5 | `output_tokens` | `int32` |  |
| 6 | `cost_usd` | `double` |  |

## `log.proto`

### message `LogRecord`

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `timestamp` | `google.protobuf.Timestamp` |  |
| 2 | `severity` | `LogSeverity` |  |
| 3 | `body` | `string` |  |
| 4 | `attributes` | `map<string, string>` |  |
| 5 | `trace_id` | `string` |  |
| 6 | `span_id` | `string` |  |

### enum `LogSeverity`

| Value | Number | Description |
|---|---|---|
| `LOG_SEVERITY_UNSPECIFIED` | 0 |  |
| `LOG_SEVERITY_DEBUG` | 1 |  |
| `LOG_SEVERITY_INFO` | 2 |  |
| `LOG_SEVERITY_WARN` | 3 |  |
| `LOG_SEVERITY_ERROR` | 4 |  |

## `metric.proto`

### message `Metric`

| # | Field | Type | Description |
|---|---|---|---|
| 1 | `name` | `string` |  |
| 2 | `labels` | `map<string, string>` |  |
| 3 | `value` | `double` |  |
| 4 | `timestamp` | `google.protobuf.Timestamp` |  |
| 5 | `type` | `MetricType` |  |

### enum `MetricType`

| Value | Number | Description |
|---|---|---|
| `METRIC_TYPE_UNSPECIFIED` | 0 |  |
| `METRIC_TYPE_GAUGE` | 1 |  |
| `METRIC_TYPE_COUNTER` | 2 |  |