Request Tracing

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

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

1
import os
2
import uuid
3
import requests
4
5
BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
6
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
7
8
request_id = str(uuid.uuid4())
9
10
resp = requests.post(
11
    f"{BASE_URL}/v2/threads",
12
    headers={
13
        "Authorization": f"Bearer {ACCESS_TOKEN}",
14
        "Content-Type": "application/json",
15
        "x-request-id": request_id,
16
    },
17
    json={"thread_name": "Test Thread"},
18
    timeout=30,
19
)
20
21
# Echoed back so you can log it alongside your own request
22
returned_id = resp.headers.get("x-request-id")
23
print(f"Sent: {request_id}  Received: {returned_id}")
24
resp.raise_for_status()

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