---
title: "Custom attributes"
subtitle: "Tag requests with the session, user, record and properties they belong to, then group and filter by them."
---

Send these fields with any gateway request or traced span. Respan indexes them, so you can see every span of a conversation, a user, or a ticket.

| Attribute | What it is | Where you use it |
|---|---|---|
| [`session_identifier`](#sessions) | One conversation: `chat_42` | The **Sessions** grouping and **Session ID** filter in Logs |
| [`customer_identifier`](#users) | Your end user: `user_8f21` | **Users & identifiers** › **Users**, with budgets and rate limits |
| [`custom_identifier`](#custom-ids) | A record in your app, like a ticket or order: `CS-1042` | **Users & identifiers** › **Custom IDs**, and the **Custom ID** filter in Logs |
| [`metadata`](#custom-properties) | Any other key-value pairs: `{"feature": "support"}` | **Custom properties** on the span, and the **Custom property** filter in Logs |

## Send them

One request can carry all of them.

<Tabs>
<Tab title="Gateway">

<Tabs>
<Tab title={"cURL"}>

```bash
curl https://gateway.respan.ai/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Draft a reply to ticket CS-1042."}],
    "session_identifier": "chat_42",
    "customer_identifier": "user_8f21",
    "custom_identifier": "CS-1042",
    "metadata": {"feature": "support"}
  }'
```

</Tab>
<Tab title={"OpenAI SDK"}>

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.respan.ai",
    api_key=os.environ["RESPAN_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Draft a reply to ticket CS-1042."}],
    extra_body={
        "session_identifier": "chat_42",
        "customer_identifier": "user_8f21",
        "custom_identifier": "CS-1042",
        "metadata": {"feature": "support"},
    },
)
```

</Tab>
<Tab title={"Anthropic SDK"}>

```python
import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.respan.ai",
    api_key=os.environ["RESPAN_API_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Draft a reply to ticket CS-1042."}],
    metadata={
        "respan_params": {
            "session_identifier": "chat_42",
            "customer_identifier": "user_8f21",
            "custom_identifier": "CS-1042",
            "metadata": {"feature": "support"},
        }
    },
)
```

</Tab>
<Tab title={"Gemini SDK"}>

```python
import os
from google import genai

client = genai.Client(
    api_key=os.environ["RESPAN_API_KEY"],
    http_options={"base_url": "https://gateway.respan.ai"},
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Draft a reply to ticket CS-1042.",
    config={
        "http_options": {
            "extra_body": {
                "respan_params": {
                    "session_identifier": "chat_42",
                    "customer_identifier": "user_8f21",
                    "custom_identifier": "CS-1042",
                    "metadata": {"feature": "support"},
                }
            }
        }
    },
)
```

</Tab>
</Tabs>

For the header and other ways to send them, see [Respan params](/docs/ai-gateway/customers/respan-params#how-to-send-them).

</Tab>
<Tab title="Tracing">

Every span created inside the block gets the attributes. Nested blocks merge, and inner values win. For setup, see the [Tracing quickstart](/docs/documentation/features/tracing/quickstart).

<Tabs>
<Tab title={"Python"}>

```python
from respan import Respan, propagate_attributes

Respan()

with propagate_attributes(
    session_identifier="chat_42",
    customer_identifier="user_8f21",
    custom_identifier="CS-1042",
    metadata={"feature": "support"},
):
    ...  # your LLM calls
```

</Tab>
<Tab title={"TypeScript"}>

```typescript
import { Respan } from "@respan/respan";

const respan = new Respan();
await respan.initialize();

await respan.propagateAttributes(
  {
    session_identifier: "chat_42",
    customer_identifier: "user_8f21",
    custom_identifier: "CS-1042",
    metadata: { feature: "support" },
  },
  async () => {
    // your LLM calls
  },
);
```

</Tab>
</Tabs>

</Tab>
</Tabs>

Logging spans with the API? These are top-level span fields. See [Create span](/docs/apis/spans/create-span).

## Sessions

A session is one conversation: every request and span with the same `session_identifier`, across as many traces as it takes. A call gets its session id from the first of these that applies:

1. The `session_identifier` you send. Use the id your app already has, such as a chat or ticket id.
2. Your framework's own conversation id, on [supported integrations](#use-your-frameworks-conversation-id).
3. A detected session, when you send [`is_auto_session_enabled: true`](#detect-sessions).

A call with none of these has no session. `thread_identifier`, the old name for `session_identifier`, still works. When a call sends both, `session_identifier` wins.

### Use your framework's conversation id

When you don't set a session id, these integrations send the framework's own conversation id as the session id. An empty id, or one longer than 255 characters, isn't used.

| Framework | Package | Session id |
|---|---|---|
| [LangChain and LangGraph](/docs/integrations/langgraph) (TypeScript) | `@respan/instrumentation-langchain` 1.2.0 or later | `thread_id` in the run config: `{ configurable: { thread_id } }` |
| [OpenAI Agents](/docs/integrations/openai-agents-sdk) (Python) | `respan-instrumentation-openai-agents` 1.2.1 or later | The trace's `group_id`: `RunConfig(group_id=...)` or `trace(..., group_id=...)` |
| [OpenAI Agents](/docs/integrations/openai-agents-sdk) (TypeScript) | `@respan/instrumentation-openai-agents` 1.3.0 or later | The trace's `groupId`: `RunConfig` `groupId` or `withTrace(name, fn, { groupId })` |
| [Mastra](/docs/integrations/mastra) | `@respan/instrumentation-mastra` 0.3.0 or later | The memory thread: `memory: { thread }` |

### Let Respan detect sessions

If your app has no conversation id, send `is_auto_session_enabled: true` and Respan finds the session for you. It's opt-in per call: only a JSON `true` turns it on, and the flag isn't stored on the log. Calls that send a session id ignore it.

<Tabs>
<Tab title="Gateway">

```python
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=history,  # the whole conversation so far
    extra_body={
        "customer_identifier": "user_8f21",
        "is_auto_session_enabled": True,
    },
)
```

It works on Chat Completions, Anthropic Messages and Responses requests, sent like any other [Respan param](/docs/ai-gateway/customers/respan-params#how-to-send-them). A response served from the gateway cache isn't given a session.

</Tab>
<Tab title="Logging API">

```json
{
  "model": "gpt-5.5",
  "customer_identifier": "user_8f21",
  "is_auto_session_enabled": true,
  "prompt_messages": [
    {"role": "user", "content": "What is the weather?"},
    {"role": "assistant", "content": "Sunny."},
    {"role": "user", "content": "And tomorrow?"}
  ],
  "completion_message": {"role": "assistant", "content": "Rain."}
}
```

Send it per row to [Create span](/docs/apis/spans/create-span) or [Create spans in bulk](/docs/apis/spans/create-spans-in-bulk). In a bulk request, rows are matched in `start_time` order, so a whole conversation sent at once lands in one session.

</Tab>
<Tab title="OpenTelemetry">

Set the span attribute `respan.sessions.is_auto_session_enabled` to the boolean `true` on the spans you export to Respan:

```python
span.set_attribute("respan.sessions.is_auto_session_enabled", True)
```

LLM spans are matched as below, and the opted-in spans of one trace share one session. The Respan SDKs don't set this attribute for you.

</Tab>
</Tabs>

How a call joins a session:

- **Resent history.** A call joins a session when its messages are an earlier call's messages plus that call's reply, which is what a chat app sends when it resends the history every turn. The earlier call must have the same project, environment and `customer_identifier`, and be less than an hour old. Otherwise the call starts a new session.
- **Responses API.** A call that sets `previous_response_id` or `conversation` joins the session of the response or conversation it continues.
- **The id.** A detected session's id starts with `auto_`. Filter by it like any other session id.
- **What's never grouped.** Evaluation and judge calls. And if two users send the same conversation with no `customer_identifier`, the next turn starts its own session rather than merging the two.

### Find a session

In **Observability** › **Logs**, switch the grouping from **Spans** to **Sessions**. Each row is one session. To find one, click **More filters**, pick **Session ID**, and enter the id. Click a session to read the conversation.

## Users

`customer_identifier` attributes a request to one of your end users. Respan keeps a record for each user: requests, tokens, cost, and activity. On gateway requests, you can also give each user a budget or a rate limit.

### Add a name and email

Send `customer_params` instead of `customer_identifier`. Only `customer_identifier` is required. `name` and `email` fill the **Name** and **Email** columns the first time Respan sees the user. Later requests don't change them.

```json
{
  "customer_params": {
    "customer_identifier": "user_8f21",
    "name": "Maya Patel",
    "email": "maya@example.com"
  }
}
```

When tracing, pass `customer_name` and `customer_email` to `propagate_attributes` next to `customer_identifier`.

A user appears the first time Respan sees its identifier. Production and test API keys keep separate records for the same identifier.

### Find a user

<Steps>
<Step title="Open the users list">

Go to **Observability** › **Users & identifiers**. The grouping reads **Users**.

<img src={"/docs/images/users/users-list-light.png"} className="block dark:hidden" alt="The Users list, grouped by Users, with each user's Customer ID, Name, Last active, Requests, Tokens and Cost" />
<img src={"/docs/images/users/users-list-dark.png"} className="hidden dark:block" alt="The Users list, grouped by Users, with each user's Customer ID, Name, Last active, Requests, Tokens and Cost" />

Each row is one `customer_identifier` with its name, email, first and last activity, requests, tokens, and cost, counted across all time. Type part of a customer ID, name, or email in **Search by users...** and press Enter. The environment switch shows **All environments**, **Production** or **Test**.

</Step>
<Step title="Open the user">

Click a row. The panel shows **Properties**, **Insights** (first seen, last active, and the current budget period), **Metrics** (tokens, cost, period usage, average TTFT and generation time) and **Budgets**.

<img src={"/docs/images/users/user-detail-light.png"} width="480" className="block dark:hidden" alt="A user's detail panel with Properties (Customer ID, Name, Email, Environment) and Insights (First seen, Last active, Period start, Period end, Updated at)" />
<img src={"/docs/images/users/user-detail-dark.png"} width="480" className="hidden dark:block" alt="A user's detail panel with Properties (Customer ID, Name, Email, Environment) and Insights (First seen, Last active, Period start, Period end, Updated at)" />

The icons in the panel header:

- **Open in Dashboard** (**Shift+D**) opens [Metrics](/docs/documentation/features/monitoring/metrics) filtered to this user.
- **Open in Logs** (**L**) opens [Logs](/docs/documentation/features/observe/explore-spans) filtered to this user's spans.
- **More actions** › **Delete user** removes the record.

To fix a name or email, click the pencil next to **Name** or **Email**, type, and press Enter.

</Step>
</Steps>

### Set a budget

Budgets apply to gateway requests only. Once a user's spend in the current period passes their **Period budget**, the gateway rejects their requests with a `402` error until the next period starts.

In **Observability** › **Users & identifiers**, click the user. Under **Budgets**, click the pencil next to **Period budget**, type an amount in USD, and press Enter. To remove the budget, clear the field and press Enter.

<img src={"/docs/images/users/user-budgets-light.png"} width="480" className="block dark:hidden" alt="The Budgets section with Total budget at $1500 and the Period budget field being edited to 250" />
<img src={"/docs/images/users/user-budgets-dark.png"} width="480" className="hidden dark:block" alt="The Budgets section with Total budget at $1500 and the Period budget field being edited to 250" />

The budget period is monthly by default. To switch it to `daily` or `weekly`, or to set the budget from code, call [Update a user](/docs/apis/users/update-user) with `budget_duration` or `period_budget`. Budget fields sent in a request's `customer_params` aren't applied.

For a rate limit that covers every user, see [Limits](/docs/ai-gateway/routing/limits).

### Limit requests per user

Rate limits apply to chat completions requests (`/api/chat/completions`). Add `rate_limit`, in requests per minute, to `customer_params`. Requests over the limit get a `429` error. Without it, the **Customer rate limit (requests/min)** set in [Limits](/docs/ai-gateway/routing/limits) applies.

```python
extra_body={
    "customer_params": {
        "customer_identifier": "user_8f21",
        "rate_limit": 60,
    }
}
```

## Custom IDs

`custom_identifier` ties a request to a record in your app, like a ticket, order, or document.

<Note>
Send `custom_identifier` as its own field. A `custom_identifier` key inside `metadata` is only a custom property, and doesn't show up under **Custom IDs**.
</Note>

### Compare custom IDs

<Steps>
<Step title="Switch to Custom IDs">

Go to **Observability** › **Users & identifiers** and switch the grouping from **Users** to **Custom IDs**.

<img src={"/docs/images/users/custom-ids-light.png"} className="block dark:hidden" alt="The Custom IDs view: metric cards for Requests, Tokens, Cost, Errors, TTFT avg, Latency avg and TPS avg, a timeline of the top five custom IDs, and a table of custom IDs" />
<img src={"/docs/images/users/custom-ids-dark.png"} className="hidden dark:block" alt="The Custom IDs view: metric cards for Requests, Tokens, Cost, Errors, TTFT avg, Latency avg and TPS avg, a timeline of the top five custom IDs, and a table of custom IDs" />

Each row is one `custom_identifier`, with its requests, tokens, cost, errors, and latency in the selected range. Click a metric card to chart the top five custom IDs by that metric.

</Step>
<Step title="Pick a time range">

Use **5m**, **1h**, **1d**, **7d** or **Custom** above the chart. The default is 7 days, and the longest range is 31 days. Drag across the chart to zoom in. Type part of an ID in **Search custom IDs...** and press Enter to find it.

</Step>
<Step title="Open a custom ID">

Click a row to see its **Properties**, **Activity**, **Metrics** and **Performance**. Click **Open in logs** (**L**) to see its spans in Logs for the same range.

</Step>
</Steps>

## Custom properties

`metadata` holds any other key-value pairs, such as the feature or region a request came from. Respan shows them as **Custom properties**, and stores the values as strings.

## Find them in Logs

In **Observability** › **Logs**, click a span and open the **Metadata** tab. The session, customer and custom IDs are under **Properties**, and your `metadata` is under **Custom properties**.

<img src={"/docs/images/users/span-identifiers-light.png"} width="480" className="block dark:hidden" alt="The Metadata tab of a span, showing Customer ID, Thread ID and Custom ID under Properties, and feature, team and region under Custom properties" />
<img src={"/docs/images/users/span-identifiers-dark.png"} width="480" className="hidden dark:block" alt="The Metadata tab of a span, showing Customer ID, Thread ID and Custom ID under Properties, and feature, team and region under Custom properties" />

Hover a row and click its filter icon to show only the spans with that value.

### Filter Logs

- **Session ID**, **Customer ID** or **Custom ID**: click **More filters**, pick the field, and enter the value.
- A custom property: click **Custom property**, search for the key, and pick a value.

See [Logs](/docs/documentation/features/observe/explore-spans) for filter groups and saved views.
