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

# Record Trace

> 
Create or update a trace within a session. Use to group related completions in agent workflows. [See SDK method.](https://docs.freeplay.ai/freeplay-sdk/traces)

Generate the trace_id client-side (UUID v4) to avoid round-trip latency.



## OpenAPI

````yaml https://app.freeplay.ai/openapi.json post /api/v2/projects/{project_id}/sessions/{session_id}/traces/id/{trace_id}
openapi: 3.1.0
info:
  title: Freeplay API
  version: 0.1.0
servers: []
security:
  - BearerAuth: []
paths:
  /api/v2/projects/{project_id}/sessions/{session_id}/traces/id/{trace_id}:
    post:
      tags:
        - Observability
      summary: Record Trace
      description: >-

        Create or update a trace within a session. Use to group related
        completions in agent workflows. [See SDK
        method.](https://docs.freeplay.ai/freeplay-sdk/traces)


        Generate the trace_id client-side (UUID v4) to avoid round-trip latency.
      operationId: post_record_trace
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
        - name: session_id
          in: path
          required: true
          schema:
            type: string
        - name: trace_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                input:
                  $ref: '#/components/schemas/JSONValue'
                output:
                  $ref: '#/components/schemas/JSONValue'
                parent_id:
                  default: null
                  title: Parent Id
                  format: uuid
                  type:
                    - string
                    - 'null'
                test_run_info:
                  default: null
                  oneOf:
                    - $ref: '#/components/schemas/TestRunInfo'
                    - type: 'null'
                agent_name:
                  default: null
                  title: Agent Name
                  type:
                    - string
                    - 'null'
                custom_metadata:
                  default: null
                  title: Custom Metadata
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                      - type: integer
                      - type: boolean
                  type:
                    - object
                    - 'null'
                eval_results:
                  default: null
                  title: Eval Results
                  additionalProperties:
                    anyOf:
                      - type: number
                      - type: boolean
                  type:
                    - object
                    - 'null'
                name:
                  default: null
                  title: Name
                  type:
                    - string
                    - 'null'
                kind:
                  default: null
                  title: Kind
                  const: tool
                  type:
                    - string
                    - 'null'
                start_time:
                  default: null
                  title: Start Time
                  format: date-time
                  type:
                    - string
                    - 'null'
                end_time:
                  default: null
                  title: End Time
                  format: date-time
                  type:
                    - string
                    - 'null'
              required:
                - input
                - output
              title: TracePayload
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                properties: {}
                title: EmptyResponse
                type: object
          description: EmptyResponse()
components:
  schemas:
    JSONValue:
      anyOf:
        - type: boolean
        - type: integer
        - type: number
        - type: string
        - additionalProperties:
            $ref: '#/components/schemas/JSONValue'
          type: object
        - items:
            $ref: '#/components/schemas/JSONValue'
          type: array
        - type: 'null'
    TestRunInfo:
      properties:
        test_run_id:
          format: uuid
          title: Test Run Id
          type: string
        test_case_id:
          format: uuid
          title: Test Case Id
          type: string
      required:
        - test_run_id
        - test_case_id
      title: TestRunInfo
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````