> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation threads in traces

> Group related LLM calls into threads for observability and analysis. Threads are a labeling mechanism and do not store or inject message history.

Threads group related [AI Router](/docs/router/using-the-router) calls into a single conversation view, letting you trace multi-turn interactions across your Deployments and Agents.

## Viewing Threads

To view Threads, head to the [Traces](/docs/observability/traces) section and select the **Threads** tab.

<Frame caption="The Threads Overview, dates, duration, traces, and costs are available to see.">
  <img src="https://mintcdn.com/orqai/ep9iJPTKd6tE7QFF/images/docs/ab5a5beacd05456232a5fd6f73cc9809ba371f3510dfdf0ab0944262c2256344-image.png?fit=max&auto=format&n=ep9iJPTKd6tE7QFF&q=85&s=abcb1ca66b14759927d183d1468521d7" alt="The Threads Overview, dates, duration, traces, and costs are available to see." width="2129" height="759" data-path="images/docs/ab5a5beacd05456232a5fd6f73cc9809ba371f3510dfdf0ab0944262c2256344-image.png" />
</Frame>

By selecting a **Thread**, you can then visualize the conversation.

<Frame caption="With each Trace you can see the Input sent to the Deployment and the resulting generation.">
  <img src="https://mintcdn.com/orqai/ep9iJPTKd6tE7QFF/images/docs/b7245c1f9a871bd20c6b0eba650390921aa37b254724056b099d936f77db841b-image.png?fit=max&auto=format&n=ep9iJPTKd6tE7QFF&q=85&s=69730cd60b3d8c4de3903af73bd734f8" alt="With each Trace you can see the Input sent to the Deployment and the resulting generation." width="4298" height="2289" data-path="images/docs/b7245c1f9a871bd20c6b0eba650390921aa37b254724056b099d936f77db841b-image.png" />

  [Deployment](/docs/deployments/overview)
</Frame>

## Adding a Generation to a Thread

**Threads** are configured at runtime when using the [Invoke](/reference/deployments/invoke) API for [Deployments](/docs/deployments/overview), or when invoking an [Agent](/docs/agents/build).

The API receives the following extra parameter:

> Conversations will be grouped by Thread ID
>
> Tags can be used to filter and search Threads in the panel.

<CodeGroup>
  ```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "thread": {
     	"id": "<unique-thread-id>",
      "tags": ["tag1", "tag2"]
    }
  }
  ```
</CodeGroup>

<Tabs>
  <Tab title="Deployment Invoke">
    <CodeGroup>
      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import os
      from orq_ai_sdk import Orq

      client = Orq(
        api_key=os.environ.get("ORQ_API_KEY", "<insert your api key here>"),
        environment="production",
      )

      generation = client.deployments.invoke(
        key="deployment-demo",
        context={"environments": []},
        metadata={"custom-field-name": "custom-metadata-value"},
        thread={
          "id": "<unique-thread-id>",
          "tags": ["tag1", "tag2"]
        }
      )

      print(generation.choices[0].message.content)
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from '@orq-ai/node';

      const client = new Orq({
        apiKey: '<insert orq api key>',
        environment: 'production'
      });

      const deployment = await client.deployments.invoke({
        key: "deployment-demo",
        context: { environments: [] },
        metadata: { "custom-field-name": "custom-metadata-value" },
        thread: {
          id: "<unique-thread-id>",
          tags: ["tag1", "tag2"]
        }
      });
      ```

      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl 'https://api.orq.ai/v2/deployments/invoke' \
      -H 'Authorization: Bearer <insert Orq API key>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      --data-raw '{
        "key": "deployment-demo",
        "context": { "environments": [] },
        "metadata": { "custom-field-name": "custom-metadata-value" },
        "thread": { "id": "<unique-thread-id>", "tags": ["tag1", "tag2"] }
      }' \
      --compressed
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Agent">
    <CodeGroup>
      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import os
      from orq_ai_sdk import Orq

      with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
          response = orq.agents.responses.create(
              agent_key="agent-demo",
              background=False,
              message={
                  "role": "user",
                  "parts": [{"kind": "text", "text": "Hello!"}]
              },
              thread={
                  "id": "<unique-thread-id>",
                  "tags": ["tag1", "tag2"]
              }
          )

          print(response)
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from '@orq-ai/node';

      const orq = new Orq({ apiKey: process.env['ORQ_API_KEY'] ?? '' });

      const response = await orq.agents.responses.create({
        background: false,
        message: {
          role: 'user',
          parts: [{ kind: 'text', text: 'Hello!' }]
        },
        thread: {
          id: '<unique-thread-id>',
          tags: ['tag1', 'tag2']
        }
      }, 'agent-demo');
      ```

      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl --request POST \
      --url 'https://api.orq.ai/v2/agents/agent-demo/responses' \
      -H 'Authorization: Bearer <insert Orq API key>' \
      -H 'Content-Type: application/json' \
      --data '{
        "message": {
          "role": "user",
          "parts": [{ "kind": "text", "text": "Hello!" }]
        },
        "thread": { "id": "<unique-thread-id>", "tags": ["tag1", "tag2"] }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Card title="AI Router Thread Management" icon="arrow-right" href="/docs/proxy/thread-management">
  Full API reference for attaching threads to **AI Router** Deployment and Agent invocations.
</Card>