## Three ways to send Respan params

You can pass Respan params three ways. They can be combined; later layers override earlier ones (`body top-level` > `respan_params` > `header`).

### 1. Top-level body fields (simplest)

Most params are accepted directly at the top level of the request body alongside standard OpenAI fields. With the OpenAI SDK, use `extra_body`.

```

```

### 2. Nested under `respan_params`

For clarity, or when using the standard API rather than the OpenAI SDK, nest the fields under `respan_params`.

```

```

The legacy key `keywordsai_params` is still accepted and merged into `respan_params`.

### 3. `X-Data-Respan-Params` header (base64-encoded JSON)

Send a `X-Data-Respan-Params` header containing base64-encoded JSON. Useful when you cannot modify the request body (for example, when proxying a third-party SDK or CLI through the gateway).

```

```

The legacy header `X-Data-Keywordsai-Params` is still accepted.

## Customer & metadata params

| Param                  | Type    | Description                                                                                                                                 |
|------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `customer_identifier`  | string  | Tag a request to a specific end-user. Drives the [Users](/content/docs/documentation/features/customer-identifier/index.html) page and per-customer analytics. |
| `metadata`             | object  | Arbitrary key-value pairs (also called **custom properties**). All values are stored as strings. Filter, group, and search logs by any key. |
| `custom_identifier`    | string  | Extra indexed tag for free-form grouping (shows as “Custom ID” in spans).                                                                     |
| `thread_identifier`    | string  | Group requests that belong to the same conversation thread.                                                                                 |
| `disable_log`         | boolean | When `true`, only metrics are recorded (no request/response payloads stored).                                                               |
| `request_breakdown`    | boolean | Returns a summarization of the response (tokens, cost, latency) inside the response body.                                                  |

### `metadata` and “custom properties”

`metadata` and “custom properties” are the same thing. **`metadata`** is the API field name; **custom properties** is the label used in the platform UI for filtering and grouping. Anything you send as `metadata` becomes a custom property on the trace and its spans.

```

```

You can then filter logs and traces by any of these keys on the [Logs page](https://platform.respan.ai/platform/requests). If you want a high-cardinality key indexed for fast filtering and aggregation, contact us to add it to your org’s indexed property list.

## Beta features (`X-Respan-Beta` header)

Opt in to experimental features via the `X-Respan-Beta` header. Send comma-separated feature flags.

```

```

| Flag                        | Description                                                                                                   |
|-----------------------------|---------------------------------------------------------------------------------------------------------------|
| `token-breakdown-2026-03-26` | Adds best-effort per-part token estimates (`system_tokens`, `tools_tokens`, `user_message_tokens`) to the log’s `properties` field.