> This page is for Alfa (Preview).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# Request Tracing

> **Warning**
>
> This API is currently in Preview.

## Overview

Every request to the Alfa API can be tagged with an `x-request-id` header. Alfa echoes the same value back on the response, making it easy to correlate a client-side call with the corresponding Alfa request.

`x-request-id` is supported on all alfa-preview endpoints, excluding gRPC endpoints.

## Behavior

| Scenario                    | Behavior                                                       |
| --------------------------- | -------------------------------------------------------------- |
| Client sends `x-request-id` | Alfa returns it on the `x-request-id` response header.         |
| Client omits `x-request-id` | Alfa does not return it on the `x-request-id` response header. |

> **Info**
>
> The header value is returned on both successful responses and error responses, so you can capture it even when a request fails.

## Recommended format

We recommend passing a UUID (v4 or v7) per logical client request. Values should be:

* Unique per request (do not reuse across retries if you want to distinguish attempts).
* Under 128 characters.
* Restricted to ASCII letters, digits, hyphens, and underscores.

## Sending x-request-id

**`send_with_request_id.py`**

```python title="send_with_request_id.py"
import os
import uuid
import requests

BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]

request_id = str(uuid.uuid4())

resp = requests.post(
    f"{BASE_URL}/v2/threads",
    headers={
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json",
        "x-request-id": request_id,
    },
    json={"thread_name": "Test Thread"},
    timeout=30,
)

# Echoed back so you can log it alongside your own request
returned_id = resp.headers.get("x-request-id")
print(f"Sent: {request_id}  Received: {returned_id}")
resp.raise_for_status()
```

**`send_with_request_id.sh`**

```bash title="send_with_request_id.sh"
REQUEST_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -i -X POST "${BASE_URL}/v2/threads" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -H "x-request-id: ${REQUEST_ID}" \
    -d '{
        "thread_name": "Test Thread"
    }'
```

## Streaming endpoints

`x-request-id` works the same way on HTTP streaming endpoints. For SSE, send the header on the initial request and read it from the response headers before the stream begins. For gRPC, it is currently ignored.

## FAQ

#### Do I have to send x-request-id?

No. If you omit it, It will be omitted from the response.

#### Should I reuse the same x-request-id across retries?

That is up to you. Reusing the same ID makes it easy to group retries together in logs;
generating a new ID per attempt makes it easier to distinguish them. We recommend a new ID
per attempt so you can differentiate the successful from failed requests.