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

# Create trace

> Store a production agent turn and its conversation history for later review



## OpenAPI

````yaml /api-reference/openapi.json post /traces
openapi: 3.1.0
info:
  title: Calibrate Public API
  version: 0.1.0
  description: Programmatic API for CI/automation. Pass your key in the `X-API-Key` header.
servers:
  - url: https://api.calibrate.artpark.ai
    description: Production
security: []
paths:
  /traces:
    post:
      tags:
        - traces
      summary: Create trace
      description: >-
        Store a production agent turn and its conversation history for later
        review
      operationId: ingest_trace_traces_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceIngest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceIngestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TraceIngest:
      properties:
        agent_id:
          type: string
          maxLength: 36
          minLength: 1
          title: Agent Id
          description: >-
            ID of the agent that produced the turn. Must be an agent in your
            workspace
        message_id:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: 'null'
          title: Message Id
          description: >-
            Your own ID for the last user message in `input`, stored for
            reference only. Omit if you have none
        conversation_id:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: 'null'
          title: Conversation Id
          description: >-
            Your own ID for the conversation this turn belongs to, stored for
            reference only. Omit if you have none
        input:
          anyOf:
            - type: string
              maxLength: 50000
              minLength: 1
            - items:
                $ref: '#/components/schemas/TraceTurn'
              type: array
              maxItems: 500
              minItems: 1
          title: Input
          description: >-
            What the agent was given for this turn. For a `general` agent, the
            standalone prompt as a string. For a `conversation` agent, the
            history up to the reported output, oldest turn first, in OpenAI chat
            format
        output:
          $ref: '#/components/schemas/TraceOutput'
          description: What the agent produced for this turn
        metadata:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceMetadataEntry'
              type: array
              maxItems: 100
            - type: 'null'
          title: Metadata
          description: >-
            Key-value pairs stored with the trace. Prefer OTel `gen_ai.*` key
            names where they fit. Omit if you have none
      additionalProperties: false
      type: object
      required:
        - agent_id
        - input
        - output
      title: TraceIngest
    TraceIngestResponse:
      properties:
        uuid:
          type: string
          maxLength: 36
          minLength: 36
          title: Uuid
          description: Unique ID for the trace
          examples:
            - f47ac10b-58cc-4372-a567-0e02b2c3d479
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
          description: The message ID you sent, if any
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: The conversation ID you sent, if any
        created_at:
          type: string
          title: Created At
          description: When the trace was created (ISO 8601 UTC)
      type: object
      required:
        - uuid
        - created_at
      title: TraceIngestResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TraceTurn:
      properties:
        role:
          type: string
          maxLength: 64
          minLength: 1
          title: Role
          description: Message author role in the conversation history
        content:
          anyOf:
            - type: string
              maxLength: 50000
            - type: 'null'
          title: Content
          description: Message text. Omit for turns that only carry tool calls
      additionalProperties: true
      type: object
      required:
        - role
      title: TraceTurn
    TraceOutput:
      properties:
        response:
          anyOf:
            - type: string
              maxLength: 50000
            - type: 'null'
          title: Response
          description: >-
            The assistant reply text for this turn. Omit for turns that only
            issued tool calls
        tool_calls:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceToolCall'
              type: array
              maxItems: 50
            - type: 'null'
          title: Tool Calls
          description: >-
            Tool calls the agent issued for this turn. Omit for plain text
            replies
      additionalProperties: false
      type: object
      title: TraceOutput
    TraceMetadataEntry:
      properties:
        key:
          type: string
          maxLength: 256
          minLength: 1
          title: Key
          description: Name of the metadata entry
        value:
          type: string
          maxLength: 8192
          title: Value
          description: Value of the metadata entry
      additionalProperties: false
      type: object
      required:
        - key
        - value
      title: TraceMetadataEntry
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    TraceToolCall:
      properties:
        tool:
          type: string
          maxLength: 255
          minLength: 1
          title: Tool
          description: Name of the tool the agent called
        arguments:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Argument values the agent passed to the tool. Omit when the call had
            none
        output:
          title: Output
          description: >-
            What the tool returned for this call. Any JSON value. Omit when you
            do not record it
      additionalProperties: false
      type: object
      required:
        - tool
      title: TraceToolCall
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

````