Skip to main content
Use Cases
  • Viewing all turns of a multi-turn conversation as a single trace in observability.
  • Debugging agent workflows by inspecting the full request sequence end-to-end.
  • Organizing support conversations to analyze resolution patterns across sessions.
  • Separating concurrent conversations from the same user to avoid mixing traces.
Group related requests into conversation Threads so they appear together in observability. Threads are a labeling mechanism and do not store or inject message history.
Threads are tracked within the orq.ai Observability stack, to learn more, see Threads.

​
Quick Start

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Start a new conversation about AI",
    "orq": {
      "thread": {
        "id": "conversation-abc123",
        "tags": ["ai-discussion", "user-123"]
      }
    }
  }'

​
Configuration

ParameterTypeRequiredDescription
idstringYesUnique thread identifier for grouping requests
tagsstring[]NoMetadata 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
// 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";

​
Use Cases

ScenarioThread ID StrategyTags Example
User Sessionsuser-{userId}-{sessionId}["user-session", "support"]
Support Ticketsticket-{ticketId}["support", "priority-high"]
A/B Testingtest-{variant}-{userId}["experiment", "variant-a"]
Multi-Step Workflowsworkflow-{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. 
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

// Initialize conversation
const userId = "user-123";
const sessionId = crypto.randomUUID();
const threadId = `user-${userId}-${sessionId}`;

const response = await client.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 client.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}`],
    },
  },
});

​
Multi-Language Support

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Explain machine learning basics",
    "orq": {
      "thread": {
        "id": "tech-discussion-001",
        "tags": ["education", "ml-basics", "beginner"]
      }
    }
  }'

​
Advanced Patterns

​
Dynamic Thread Management

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

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 client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Urgent: System not responding" }],
  orq: {
    thread: {
      id: createThreadId(threadConfig),
      tags: generateTags(threadConfig),
    },
  },
});

​
Batch Thread Processing

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

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 client.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}`],
        },
      },
    });
  }),
);

​
Conversation Flow Tracking

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

// Track conversation progression
const conversationSteps = [
  "greeting",
  "problem-identification",
  "solution-proposal",
  "confirmation",
];

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

​
Troubleshooting

IssueCauseSolution
Requests not grouping togetherDifferent thread IDs used across requestsUse a consistent thread ID for all requests in the same session or workflow
Thread overlapNon-unique thread IDs shared across sessionsUse UUID or timestamp-based IDs