> ## 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.

# Thread management for grouped requests

> Group related AI Router requests into conversation threads for observability. Threads label related calls together without storing message history.

Group related requests into conversation [Threads](/docs/observability/threads) so they appear together in observability. Threads are a labeling mechanism and do not store or inject message history.

<Info>
  [Threads](/docs/observability/threads) are tracked within the orq.ai Observability stack, to learn more, see [Threads](/docs/observability/threads).
</Info>

## Quick Start

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Start a new conversation about AI" }],
    orq: {
      thread: {
        id: `conversation-${crypto.randomUUID()}`,
        tags: ["ai-discussion", "user-123"],
      },
    },
  });
  ```
</CodeGroup>

## Configuration

| Parameter | Type      | Required | Description                                    |
| --------- | --------- | -------- | ---------------------------------------------- |
| `id`      | string    | Yes      | Unique thread identifier for grouping requests |
| `tags`    | string\[] | No       | Metadata tags for filtering and categorization |

## Best Practices

1. **Consistent Naming**: Use predictable thread ID patterns
2. **Meaningful Tags**: Choose tags that aid in filtering and analysis
3. **Session Management**: Tie thread IDs to user sessions
4. **Unique IDs**: Use UUIDs or composite keys to avoid cross-session overlap

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Good: Descriptive and unique
  const threadId = `support-${userId}-${sessionId}-${timestamp}`;

  // Good: UUID-based for uniqueness
  const threadId = `conversation-${crypto.randomUUID()}`;

  // Avoid: Too generic
  const threadId = "conversation1";
  ```
</CodeGroup>

## Use Cases

| Scenario                 | Thread ID Strategy          | Tags Example                   |
| ------------------------ | --------------------------- | ------------------------------ |
| **User Sessions**        | `user-{userId}-{sessionId}` | `["user-session", "support"]`  |
| **Support Tickets**      | `ticket-{ticketId}`         | `["support", "priority-high"]` |
| **A/B Testing**          | `test-{variant}-{userId}`   | `["experiment", "variant-a"]`  |
| **Multi-Step Workflows** | `workflow-{processId}`      | `["onboarding", "step-2"]`     |

## Implementation Examples

### Session-Based Threading

Assign the same `thread.id` to all requests in a session to group them together in observability. Your application manages the messages array for each request.

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Initialize conversation
  const sessionId = generateSessionId();
  const threadId = `user-${userId}-${sessionId}`;

  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "How do I reset my password?" }],
    orq: {
      thread: {
        id: threadId,
        tags: ["support", "password-reset", `user-${userId}`],
      },
    },
  });

  // Continue conversation
  const followUp = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [
      { role: "user", content: "How do I reset my password?" },
      { role: "assistant", content: response.choices[0].message.content },
      { role: "user", content: "I didn't receive the reset email" },
    ],
    orq: {
      thread: {
        id: threadId, // Same thread ID
        tags: ["support", "email-issue", `user-${userId}`],
      },
    },
  });
  ```
</CodeGroup>

### Multi-Language Support

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/chat/completions \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [{"role": "user", "content": "Start technical discussion"}],
      "orq": {
        "thread": {
          "id": "tech-discussion-001",
          "tags": ["technical", "architecture"]
        }
      }
    }'
  ```

  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";
  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const threadId = `conversation-${crypto.randomUUID()}`;

  const response = await client.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Explain machine learning basics" }],
    orq: {
      thread: {
        id: threadId,
        tags: ["education", "ml-basics", "beginner"],
      },
    },
  });
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import openai
  import uuid

  client = openai.OpenAI(
      api_key=os.environ["ORQ_API_KEY"],
      base_url="https://api.orq.ai/v3/router"
  )

  thread_id = f"conversation-{uuid.uuid4()}"

  response = client.chat.completions.create(
      model="openai/gpt-4o",
      messages=[{"role": "user", "content": "Explain machine learning basics"}],
      extra_body={
          "orq": {
              "thread": {
                  "id": thread_id,
                  "tags": ["education", "ml-basics", "beginner"]
              }
          }
      }
  )
  ```
</CodeGroup>

## Advanced Patterns

### Dynamic Thread Management

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  interface ThreadConfig {
    userId: string;
    sessionType: "support" | "sales" | "general";
    priority?: "low" | "medium" | "high";
  }

  function createThreadId(config: ThreadConfig): string {
    const timestamp = Date.now();
    return `${config.sessionType}-${config.userId}-${timestamp}`;
  }

  function generateTags(config: ThreadConfig): string[] {
    const baseTags = [config.sessionType, `user-${config.userId}`];

    if (config.priority) {
      baseTags.push(`priority-${config.priority}`);
    }

    return baseTags;
  }

  const threadConfig: ThreadConfig = {
    userId: "user123",
    sessionType: "support",
    priority: "high",
  };

  const response = await openai.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Urgent: System not responding" }],
    orq: {
      thread: {
        id: createThreadId(threadConfig),
        tags: generateTags(threadConfig),
      },
    },
  });
  ```
</CodeGroup>

### Batch Thread Processing

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const conversations = [
    { userId: "user1", message: "Question about billing" },
    { userId: "user2", message: "Technical support needed" },
    { userId: "user3", message: "Feature request" },
  ];

  const responses = await Promise.all(
    conversations.map(async (conv, index) => {
      return openai.chat.completions.create({
        model: "openai/gpt-4o",
        messages: [{ role: "user", content: conv.message }],
        orq: {
          thread: {
            id: `batch-${Date.now()}-${index}`,
            tags: ["batch-processing", `user-${conv.userId}`],
          },
        },
      });
    }),
  );
  ```
</CodeGroup>

### Conversation Flow Tracking

<CodeGroup>
  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Track conversation progression
  const conversationSteps = [
    "greeting",
    "problem-identification",
    "solution-proposal",
    "confirmation",
  ];

  async function processConversationStep(step: string, threadId: string, message: string) {
    return await openai.chat.completions.create({
      model: "openai/gpt-4o",
      messages: [{ role: "user", content: message }],
      orq: {
        thread: {
          id: threadId,
          tags: ["workflow", `step-${step}`, "customer-service"],
        },
      },
    });
  }
  ```
</CodeGroup>

## Troubleshooting

| Issue                          | Cause                                        | Solution                                                                    |
| ------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------- |
| Requests not grouping together | Different thread IDs used across requests    | Use a consistent thread ID for all requests in the same session or workflow |
| Thread overlap                 | Non-unique thread IDs shared across sessions | Use UUID or timestamp-based IDs                                             |