> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Agent IDs And Run IDs > Attach agent, run, session, request, and trace identifiers to Alephant Gateway traffic Agent IDs and Run IDs are the minimum context needed to turn model requests into agent run records. Without these identifiers, Alephant can still log a gateway request against a Virtual Key. With them, Alephant can group requests into agent runs, connect those runs to sessions and workflows, and make cost, policy, and debugging views much more useful. ## Identifier Model | Identifier | Scope | Who creates it | When to reuse it | | ---------- | ------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- | | Agent ID | Stable agent identity | Alephant dashboard or SaaS API | Reuse for every request from the same agent | | Run ID | One task execution | Your application, framework, or workflow | Reuse for every model/tool call in the same task | | Session ID | Multi-turn conversation or workflow session | Your application, framework, or workflow | Reuse across related runs in one session | | Request ID | One gateway request | Your application or Alephant | Use one unique value per HTTP request | | Trace ID | Cross-service or payment-grade trace | Alephant or your distributed tracing layer | Reuse across payment, execution, and cost records when available | ## Required Headers For Agent Runs Send these headers with gateway requests when you want requests to appear under an agent run: | Header | Required | Purpose | | --------------------- | -------------------------- | -------------------------------------------------------------------- | | `Authorization` | Yes | `Bearer ` authenticates the scoped Agent or Virtual Key | | `Alephant-Agent-Id` | Recommended for agent runs | Stable Alephant agent ID | | `Alephant-Run-Id` | Recommended for agent runs | Stable ID for one task execution | | `x-request-id` | Recommended | Unique ID for this individual request | | `alephant-session-id` | Optional | Groups multiple runs or requests into a session | | `alephant-property-*` | Optional | Adds safe operational metadata for search and analytics | Older snippets may show `X-Alephant-Agent`. Prefer `Alephant-Agent-Id` in new integrations. ## Naming Recommendations Use IDs that are stable, searchable, and safe to store in logs. Good examples: ```text Alephant-Agent-Id: agt_support_bot_8f3a Alephant-Run-Id: run_ticket_8421_20260609_001 alephant-session-id: sess_customer_123_support_20260609 x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001 ``` Avoid putting secrets, raw customer email addresses, access tokens, or regulated personal data in IDs or `alephant-property-*` headers. ## Curl Example ```bash curl https://ai.alephant.io/v1/chat/completions \ -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \ -H "Content-Type: application/json" \ -H "Alephant-Agent-Id: agt_support_bot_8f3a" \ -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \ -H "alephant-session-id: sess_customer_123_support_20260609" \ -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \ -H "alephant-property-workflow: support-triage" \ -H "alephant-property-environment: production" \ -d '{ "model": "openai/gpt-4o-mini", "messages": [ { "role": "user", "content": "Summarize this support ticket and suggest the next action." } ] }' ``` ## TypeScript Example Use default headers when every request from a client instance belongs to the same agent run. ```typescript import OpenAI from "openai"; const agentId = "agt_support_bot_8f3a"; const runId = "run_ticket_8421_20260609_001"; const sessionId = "sess_customer_123_support_20260609"; const client = new OpenAI({ apiKey: process.env.ALEPHANT_VIRTUAL_KEY, baseURL: "https://ai.alephant.io/v1", defaultHeaders: { "Alephant-Agent-Id": agentId, "Alephant-Run-Id": runId, "alephant-session-id": sessionId, "alephant-property-workflow": "support-triage", "alephant-property-environment": "production", }, }); const response = await client.chat.completions.create({ model: "openai/gpt-4o-mini", messages: [ { role: "user", content: "Summarize this support ticket and suggest the next action.", }, ], }); ``` If one process handles many runs, create a client per run or pass request-specific headers through the SDK request options your runtime supports. ## Python Example ```python import os from openai import OpenAI agent_id = "agt_support_bot_8f3a" run_id = "run_ticket_8421_20260609_001" session_id = "sess_customer_123_support_20260609" client = OpenAI( api_key=os.environ["ALEPHANT_VIRTUAL_KEY"], base_url="https://ai.alephant.io/v1", default_headers={ "Alephant-Agent-Id": agent_id, "Alephant-Run-Id": run_id, "alephant-session-id": session_id, "alephant-property-workflow": "support-triage", "alephant-property-environment": "production", }, ) response = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[ { "role": "user", "content": "Summarize this support ticket and suggest the next action.", } ], ) ``` ## Multi-Step Run Pattern Use the same `Alephant-Run-Id` for every model or tool call inside one task. ```text run_ticket_8421_20260609_001 request 1: classify ticket request 2: retrieve policy summary request 3: draft customer reply request 4: score escalation risk ``` Use a new `Alephant-Run-Id` when the agent starts a different task, even if it belongs to the same user session. ```text sess_customer_123_support_20260609 run_ticket_8421_20260609_001 run_refund_check_8421_20260609_002 run_followup_email_8421_20260609_003 ``` ## n8n Workflow Pattern For n8n workflows, use the n8n execution ID or a workflow-generated ID as the run ID. Recommended mapping: | n8n concept | Alephant field | | --------------------------------- | ---------------------------- | | Workflow or automation name | `alephant-property-workflow` | | Execution ID | `Alephant-Run-Id` | | Customer, ticket, or job grouping | `alephant-session-id` | | Alephant Agent for the workflow | `Alephant-Agent-Id` | If you use the Alephant n8n community nodes, pass the returned `requestId` or `requestLogId` into later analytics steps. If you call the gateway through an n8n HTTP Request node, include the trace headers directly. ## Paid Endpoint And Trace ID Notes For paid endpoints, `trace_id` is used for financial-grade reconciliation across payment, settlement, execution, model cost, tool cost, and revenue records. Do not replace `Alephant-Run-Id` with `trace_id`. Use them together: * `Alephant-Run-Id` describes the agent task. * `trace_id` links the financial and execution records for paid endpoint activity. * `x-request-id` identifies an individual gateway request. If paid endpoint activity has missing trace context, revenue and margin views may mark the call as incomplete or unattributed. ## Verification Checklist After sending requests: 1. Open **Logs** and search by `x-request-id`, run ID, or agent ID. 2. Open the Agent detail page and check the Runs view. 3. Confirm request cost, tokens, model, provider, and latency appear under the expected Agent. 4. If the run belongs to a workflow, confirm all related requests share the same Run ID. 5. If the workflow is monetized, confirm payment activity and cost records share trace context. ## Related Pages * [Agent Run Tracing](/docs/overview/core-concepts/agent-run-tracing) * [Agents & Routing](/docs/overview/core-concepts/agents-routing) * [Gateway Integration](/docs/overview/core-concepts/gateway-integration) * [n8n Workflow Governance](/sdk-reference/workflow-integrations/n-8-n-workflow-governance)