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

# Submit Trace

> Record a single agent run from an external framework

Creates a `PromptTrace` document in your workspace and auto-creates (or updates) a **reference Robot** representing this external agent on the AgentX platform.

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your workspace API key.
</ParamField>

## Body

<ParamField body="name" type="string" required>
  Agent or operation label shown in the UI.
</ParamField>

<ParamField body="input" type="any">
  Agent input: string, JSON object, array, etc.
</ParamField>

<ParamField body="output" type="any">
  Agent output.
</ParamField>

<ParamField body="latency_ms" type="number">
  End-to-end wall-clock latency in milliseconds.
</ParamField>

<ParamField body="error" type="string">
  Error message if the agent run failed.
</ParamField>

<ParamField body="framework" type="string">
  Framework identifier: `"langchain"`, `"crewai"`, `"openai-agents"`, `"anthropic"`, or any custom string.
</ParamField>

<ParamField body="model" type="string">
  LLM model used, e.g. `"gpt-4o"`, `"claude-sonnet-4-6"`.
</ParamField>

<ParamField body="tool_calls" type="array">
  Up to 50 tool calls made during the run. Excess is silently truncated.

  ```json theme={null}
  [
    {
      "name": "search_knowledge_base",
      "input": "password reset",
      "output": "...",
      "latency_ms": 210
    }
  ]
  ```
</ParamField>

<ParamField body="session_id" type="string">
  Groups traces from the same user session or thread.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata. Not indexed. No enforced size limit.
</ParamField>

<ParamField body="workspaceId" type="string">
  Explicit workspace ObjectId. Defaults to your API key's workspace.
</ParamField>

<ParamField body="timestamp" type="string">
  ISO 8601 timestamp to use as the trace's `createdAt` instead of the ingest time, useful for backfilling.
</ParamField>

<ParamField body="performance_summary" type="object">
  Arbitrary performance breakdown object, stored verbatim (e.g. `{ total_duration_ms }`).
</ParamField>

<ParamField body="input_tokens" type="number">
  Input token count. Stored as `inputTokenSize` when greater than 0.
</ParamField>

<ParamField body="output_tokens" type="number">
  Output token count. Stored as `outputTokenSize` when greater than 0.
</ParamField>

<ParamField body="monitor" type="boolean">
  When `true`, check this trace against [Monitor](/sdk/monitor) patterns immediately, with no dashboard profile required.
</ParamField>

<ParamField body="pattern_ids" type="array">
  Custom pattern ids (from [`POST /monitor/patterns`](/sdk/monitor)) to restrict detection to. Only meaningful alongside `monitor: true`; omit to run the full default sweep (built-in checks plus every pattern enabled for the workspace) instead.
</ParamField>

## Response

<ResponseField name="trace_id" type="string">
  ID of the created trace. Use this with `evaluate_trace()` or `POST /ingest/traces/:id/evaluate`.
</ResponseField>

<ResponseField name="reference_agent_id" type="string">
  ID of the reference Robot created or reused for this agent name. Appears in the AgentX UI.
</ResponseField>

<ResponseField name="queued" type="boolean">
  Always `false`; traces are written synchronously.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:4700/api/v1/ingest/traces \
    -H "x-api-key: a1b2c3d4e5f60718293a4b5c6d7e8f9012345678" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "customer-support-agent",
      "framework": "langchain",
      "model": "gpt-4o",
      "input": "How do I reset my password?",
      "output": "Click Forgot Password on the login page.",
      "latency_ms": 1340,
      "tool_calls": [
        { "name": "search_kb", "input": "password reset", "output": "...", "latency_ms": 210 }
      ],
      "session_id": "user_session_abc123"
    }'
  ```

  ```python Python SDK (decorator) theme={null}
  from agentx import AgentX

  client = AgentX.from_env()

  @client.tracer.trace("customer-support-agent", framework="langchain", model="gpt-4o")
  def handle(query: str) -> str:
      return chain.invoke(query)

  handle("How do I reset my password?")
  ```

  ```python Python SDK (get trace_id back) theme={null}
  from agentx import AgentX

  client = AgentX.from_env()

  # sync=True blocks until the trace is ingested, so trace_id is available as soon as the
  # `with` block exits. The decorator form above is fire-and-forget and never returns an id.
  with client.tracer.trace(
      "customer-support-agent", framework="langchain", model="gpt-4o", sync=True
  ) as span:
      span.output = chain.invoke("How do I reset my password?")

  print(span.trace_id)  # "6876abc123def456789abc01"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "trace_id": "6876abc123def456789abc01",
    "reference_agent_id": "6876def456abc789012345cd",
    "queued": false
  }
  ```
</ResponseExample>