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

# Create Log Span

> Log individual spans within traces.



## OpenAPI

````yaml POST /logs/span
openapi: 3.1.1
info:
  title: Adaline API
  version: 2.0.0
  description: >-
    Public API for managing Adaline projects, prompts, datasets, evaluators,
    evaluations, providers, models, and deployments.


    Generated from Zod schemas — this spec is the single source of truth.
servers:
  - url: https://api.adaline.ai/v2
    description: Production API
security: []
tags:
  - name: datasets
    description: Manage prompt datasets and their columns and rows.
  - name: projects
    description: List and manage Adaline projects.
  - name: providers
    description: List configured LLM providers and their settings.
  - name: models
    description: List available models across providers.
  - name: prompts
    description: Create and manage prompts and their drafts.
  - name: evaluators
    description: Configure evaluators attached to a prompt.
  - name: evaluations
    description: Run and inspect evaluation results.
  - name: deployments
    description: Retrieve deployed prompt snapshots.
  - name: logs
    description: Ingest execution traces and spans for observability.
paths:
  /logs/span:
    post:
      tags:
        - logs
      summary: Create span log
      description: Log individual spans within traces.
      operationId: createLogSpan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLogSpanRequest'
      responses:
        '200':
          description: Span log created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLogSpanResponse'
          headers:
            X-Request-Id:
              description: >-
                Unique identifier for the request. Returned in every response.
                Send a custom value to correlate requests, or omit to receive a
                generated UUID.
              schema:
                type: string
                format: uuid
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — invalid or unauthorized API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large — span content exceeds max size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateLogSpanRequest:
      title: Create Log Span Request
      type: object
      description: Request payload for creating a new span within an existing trace.
      required:
        - projectId
        - span
      properties:
        projectId:
          $ref: '#/components/schemas/BaseEntityId'
          description: The unique identifier of the project.
        span:
          $ref: '#/components/schemas/CreateLogSpanRequestSpan'
          description: Span data for creating a new span linked to an existing trace
    CreateLogSpanResponse:
      title: Create Log Span Response
      type: object
      description: >-
        Response containing created span ID for tracking in observability
        system.
      required:
        - spanId
      properties:
        spanId:
          $ref: '#/components/schemas/BaseEntityId'
          description: The unique identifier of the span created in Adaline.
    ErrorResponse:
      title: Error Response
      type: object
      description: >-
        Standard error response envelope. Permits backend-specific sibling
        fields (e.g. Zod issue details) alongside the typed `error`.
      properties:
        error:
          description: >-
            Error details — typed envelope, or a raw string reason when the
            backend's validator produces a short summary (e.g. Zod validation
            fallback).
          oneOf:
            - type: string
            - type: object
              properties:
                code:
                  type: string
                  description: Machine-readable error code.
                  enum:
                    - VALIDATION_ERROR
                    - INVALID_CURSOR
                    - AUTHENTICATION_REQUIRED
                    - FORBIDDEN
                    - RESOURCE_NOT_FOUND
                    - CONFLICT
                    - PAYLOAD_TOO_LARGE
                    - RATE_LIMITED
                    - INTERNAL_ERROR
                message:
                  type: string
                  description: Human-readable error message.
                details:
                  type: array
                  description: Optional field-level validation details.
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                      issue:
                        type: string
                    required:
                      - field
                      - issue
              required:
                - code
                - message
              additionalProperties: true
      required:
        - error
      additionalProperties: true
    BaseEntityId:
      title: Base Entity ID
      type: string
      description: Unique identifier for an entity, between 20 and 80 characters.
      minLength: 20
      maxLength: 80
    CreateLogSpanRequestSpan:
      title: Create Log Span Request Span
      type: object
      description: Span data for creating a new span linked to an existing trace.
      required:
        - startedAt
        - endedAt
        - name
        - status
        - content
      properties:
        traceId:
          description: >-
            The ID of an existing trace (required if traceReferenceId not
            provided).
          anyOf:
            - $ref: '#/components/schemas/BaseEntityId'
            - type: 'null'
        traceReferenceId:
          type:
            - string
            - 'null'
          description: >-
            The reference ID of an existing trace (required if traceId not
            provided). This is usually the traceId used within your application
            / system.
          minLength: 1
          maxLength: 128
        promptId:
          anyOf:
            - $ref: '#/components/schemas/BaseEntityId'
              description: >-
                The unique identifier of the prompt used. If not provided, you
                will not be able to view the span in prompt's monitor section.
            - type: 'null'
        deploymentId:
          anyOf:
            - $ref: '#/components/schemas/BaseEntityId'
              description: The deployment ID used for this span.
            - type: 'null'
        startedAt:
          $ref: '#/components/schemas/UnixTimestamp'
          description: Unix timestamp when the span started.
        endedAt:
          $ref: '#/components/schemas/UnixTimestamp'
          description: Unix timestamp when the span ended.
        name:
          type: string
          description: Name for the span.
          minLength: 1
          maxLength: 256
        status:
          type: string
          description: Status of the span.
          enum:
            - success
            - failure
            - aborted
            - cancelled
            - unknown
        content:
          $ref: '#/components/schemas/LogSpanContent'
        runEvaluation:
          type:
            - boolean
            - 'null'
          description: >-
            Whether to run evaluation on this span. Overrides the continuous
            evaluation sample rate for the span.
        parentReferenceId:
          type:
            - string
            - 'null'
          description: >-
            Reference ID of the parent span. This is usually this span's
            parent's spanId used within your application / system.
          minLength: 1
          maxLength: 128
        referenceId:
          type:
            - string
            - 'null'
          description: >-
            External reference ID for the span. This is usually the spanId used
            within your application / system.
          minLength: 1
          maxLength: 128
        sessionId:
          type:
            - string
            - 'null'
          description: >-
            Session ID associated with the span. This is usually the sessionId /
            threadId / chatId used within your application / system.
          minLength: 1
          maxLength: 128
        attributes:
          anyOf:
            - $ref: '#/components/schemas/LogAttributes'
            - type: 'null'
        tags:
          anyOf:
            - $ref: '#/components/schemas/LogTags'
            - type: 'null'
    UnixTimestamp:
      title: Unix Timestamp
      type: integer
      format: int64
      description: Unix timestamp in milliseconds.
      minimum: 1672511400000
      maximum: 33229420200000
    LogSpanContent:
      title: Log Span Content
      description: >-
        Polymorphic content type for different span categories in LLM
        observability tracing.
      oneOf:
        - $ref: '#/components/schemas/LogSpanModelContent'
          title: Model
        - $ref: '#/components/schemas/LogSpanModelStreamContent'
          title: Model Stream
        - $ref: '#/components/schemas/LogSpanEmbeddingsContent'
          title: Embeddings
        - $ref: '#/components/schemas/LogSpanFunctionContent'
          title: Function
        - $ref: '#/components/schemas/LogSpanToolContent'
          title: Tool
        - $ref: '#/components/schemas/LogSpanGuardrailContent'
          title: Guardrail
        - $ref: '#/components/schemas/LogSpanRetrievalContent'
          title: Retrieval
        - $ref: '#/components/schemas/LogSpanOtherContent'
          title: Other
      discriminator:
        propertyName: type
        mapping:
          Model:
            $ref: '#/components/schemas/LogSpanModelContent'
          ModelStream:
            $ref: '#/components/schemas/LogSpanModelStreamContent'
          Embeddings:
            $ref: '#/components/schemas/LogSpanEmbeddingsContent'
          Function:
            $ref: '#/components/schemas/LogSpanFunctionContent'
          Tool:
            $ref: '#/components/schemas/LogSpanToolContent'
          Guardrail:
            $ref: '#/components/schemas/LogSpanGuardrailContent'
          Retrieval:
            $ref: '#/components/schemas/LogSpanRetrievalContent'
          Other:
            $ref: '#/components/schemas/LogSpanOtherContent'
    LogAttributes:
      title: Log Attributes
      type: object
      additionalProperties:
        oneOf:
          - type: string
          - type: number
          - type: boolean
      description: Key-value pairs for log metadata.
    LogTags:
      title: Log Tags
      type: array
      items:
        type: string
        minLength: 1
        maxLength: 256
      description: Array of strings for log metadata.
    LogSpanModelContent:
      title: Log Span Model Content
      type: object
      description: >-
        Content for LLM model inference span with input/output and metadata for
        observability, see
        [here](https://adaline.ai/docs/instrument/advanced-usage#span-content-input-and-output)
        for more details.
      properties:
        type:
          type: string
          enum:
            - Model
        provider:
          type: string
          description: Provider name in lowercase.
          minLength: 1
          maxLength: 512
        model:
          type: string
          description: Model name as defined in the provider's API.
          minLength: 1
          maxLength: 512
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
          description: >-
            JSON string that must be valid JSON, see
            [here](https://adaline.ai/docs/instrument/advanced-usage#span-content-input-and-output)
            for more details
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
          description: >-
            JSON string that must be valid JSON, see
            [here](https://adaline.ai/docs/instrument/advanced-usage#span-content-input-and-output)
            for more details
        variables:
          anyOf:
            - $ref: '#/components/schemas/LogSpanVariable'
            - type: 'null'
        cost:
          type:
            - number
            - 'null'
          description: >-
            Cost of inference in USD, overrides the automatic cost calculated by
            Adaline.
          minimum: 0
    LogSpanModelStreamContent:
      title: Log Span Model Stream Content
      type: object
      description: >-
        Content for streaming LLM model inference with chunked output and final
        aggregated result.
      required:
        - type
        - provider
        - model
        - input
        - output
        - aggregateOutput
      properties:
        type:
          type: string
          enum:
            - ModelStream
        provider:
          type: string
          description: Provider name in lowercase.
          minLength: 1
          maxLength: 512
        model:
          type: string
          description: Model name as defined in the provider's API.
          minLength: 1
          maxLength: 512
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
          description: >-
            JSON string that must be valid JSON, see
            [here](https://adaline.ai/docs/instrument/advanced-usage#span-content-input-and-output)
            for more details
        output:
          type: string
          description: Stream output as string
        aggregateOutput:
          $ref: '#/components/schemas/LogSpanContentJson'
          description: >-
            JSON string that must be valid JSON, see
            [here](https://adaline.ai/docs/instrument/advanced-usage#span-content-input-and-output)
            for more details
        variables:
          anyOf:
            - $ref: '#/components/schemas/LogSpanVariable'
            - type: 'null'
        cost:
          type:
            - number
            - 'null'
          description: >-
            Cost of inference in USD, overrides the automatic cost calculated by
            Adaline.
          minimum: 0
    LogSpanEmbeddingsContent:
      title: Log Span Embeddings Content
      type: object
      description: >-
        Content for embedding generation span for vector database operations and
        semantic search.
      required:
        - type
        - input
        - output
      properties:
        type:
          type: string
          enum:
            - Embeddings
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
    LogSpanFunctionContent:
      title: Log Span Function Content
      type: object
      description: Content for function execution span tracking custom application logic.
      required:
        - type
        - input
        - output
      properties:
        type:
          type: string
          enum:
            - Function
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
    LogSpanToolContent:
      title: Log Span Tool Content
      type: object
      description: Content for tool/API call execution span tracking external integrations.
      required:
        - type
        - input
        - output
      properties:
        type:
          type: string
          enum:
            - Tool
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
    LogSpanGuardrailContent:
      title: Log Span Guardrail Content
      type: object
      description: >-
        Content for guardrail/safety check span ensuring LLM output compliance
        and safety.
      required:
        - type
        - input
        - output
      properties:
        type:
          type: string
          enum:
            - Guardrail
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
    LogSpanRetrievalContent:
      title: Log Span Retrieval Content
      type: object
      description: >-
        Content for retrieval/RAG span tracking document search and context
        injection.
      required:
        - type
        - input
        - output
      properties:
        type:
          type: string
          enum:
            - Retrieval
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
    LogSpanOtherContent:
      title: Log Span Other Content
      type: object
      description: Content for custom span types not covered by standard categories.
      required:
        - type
        - input
        - output
      properties:
        type:
          type: string
          enum:
            - Other
        input:
          $ref: '#/components/schemas/LogSpanContentJson'
        output:
          $ref: '#/components/schemas/LogSpanContentJson'
    LogSpanContentJson:
      title: Log Span Content JSON
      type: string
      minLength: 1
      description: JSON string that must be valid JSON.
    LogSpanVariable:
      title: Log Span Variable
      type: object
      description: Object containing variable values used in the model call.
      required:
        - name
        - value
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: The name of the variable
        value:
          oneOf:
            - $ref: '#/components/schemas/TextContent'
            - $ref: '#/components/schemas/ImageContent'
            - $ref: '#/components/schemas/PdfContent'
            - $ref: '#/components/schemas/ReasoningContent'
            - $ref: '#/components/schemas/ToolCallContent'
            - $ref: '#/components/schemas/ToolResponseContent'
          discriminator:
            propertyName: modality
            mapping:
              text:
                $ref: '#/components/schemas/TextContent'
              image:
                $ref: '#/components/schemas/ImageContent'
              pdf:
                $ref: '#/components/schemas/PdfContent'
              reasoning:
                $ref: '#/components/schemas/ReasoningContent'
              tool-call:
                $ref: '#/components/schemas/ToolCallContent'
              tool-response:
                $ref: '#/components/schemas/ToolResponseContent'
          description: Value of the variable.
    TextContent:
      type: object
      title: Text Content
      description: Text content type for prompt messages.
      required:
        - modality
        - value
      properties:
        modality:
          type: string
          enum:
            - text
        value:
          type: string
    ImageContent:
      type: object
      title: Image Content
      description: Image content type for prompt messages with detail level specification.
      required:
        - modality
        - detail
        - value
      properties:
        modality:
          type: string
          enum:
            - image
        detail:
          type: string
          enum:
            - low
            - medium
            - high
            - auto
        value:
          $ref: '#/components/schemas/ImageContentValue'
    PdfContent:
      type: object
      title: PDF Content
      description: PDF document content type for prompt messages with file metadata.
      required:
        - modality
        - value
        - file
      properties:
        modality:
          type: string
          enum:
            - pdf
        value:
          $ref: '#/components/schemas/PdfContentValue'
        file:
          type: object
          required:
            - name
            - id
          properties:
            name:
              type: string
            id:
              type: string
            size:
              type:
                - number
                - 'null'
    ReasoningContent:
      type: object
      title: Reasoning Content
      description: >-
        Reasoning content type for LLM chain-of-thought and extended thinking
        responses.
      required:
        - modality
        - value
      properties:
        modality:
          type: string
          enum:
            - reasoning
        value:
          $ref: '#/components/schemas/ReasoningContentValueUnion'
    ToolCallContent:
      type: object
      title: Tool Call Content
      description: Tool/function call request from LLM with arguments and metadata.
      required:
        - modality
        - index
        - id
        - name
        - arguments
      properties:
        modality:
          type: string
          enum:
            - tool-call
        index:
          type: integer
          minimum: 0
        id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        arguments:
          type: string
        serverName:
          type:
            - string
            - 'null'
    ToolResponseContent:
      type: object
      title: Tool Response Content
      description: >-
        Tool/function execution response returned to LLM with result data and
        optional API metadata.
      required:
        - modality
        - index
        - id
        - name
        - data
      properties:
        modality:
          type: string
          enum:
            - tool-response
        index:
          type: integer
          minimum: 0
        id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        data:
          type: string
        apiResponse:
          type:
            - object
            - 'null'
          properties:
            statusCode:
              type: integer
              minimum: 0
    ImageContentValue:
      title: Image Content Value
      description: Union type for image content - either base64 encoded or URL reference.
      oneOf:
        - $ref: '#/components/schemas/Base64ImageContentValue'
          title: Base64
        - $ref: '#/components/schemas/UrlImageContentValue'
          title: URL
        - $ref: '#/components/schemas/Base64HostedImageContentValue'
          title: Base64 Hosted
      discriminator:
        propertyName: type
        mapping:
          base64:
            $ref: '#/components/schemas/Base64ImageContentValue'
          url:
            $ref: '#/components/schemas/UrlImageContentValue'
          base64-hosted:
            $ref: '#/components/schemas/Base64HostedImageContentValue'
    PdfContentValue:
      title: PDF Content Value
      description: Union type for PDF content - either base64 encoded or URL reference.
      oneOf:
        - $ref: '#/components/schemas/Base64PdfContentValue'
          title: Base64
        - $ref: '#/components/schemas/UrlPdfContentValue'
          title: URL
        - $ref: '#/components/schemas/Base64HostedPdfContentValue'
          title: Base64 Hosted
      discriminator:
        propertyName: type
        mapping:
          base64:
            $ref: '#/components/schemas/Base64PdfContentValue'
          url:
            $ref: '#/components/schemas/UrlPdfContentValue'
          base64-hosted:
            $ref: '#/components/schemas/Base64HostedPdfContentValue'
    ReasoningContentValueUnion:
      title: Reasoning Content Value Union
      description: >-
        Union type for reasoning content - either full thinking or redacted
        version.
      oneOf:
        - $ref: '#/components/schemas/ReasoningContentValue'
          title: Thinking
        - $ref: '#/components/schemas/RedactedReasoningContentValue'
          title: Redacted
      discriminator:
        propertyName: type
        mapping:
          thinking:
            $ref: '#/components/schemas/ReasoningContentValue'
          redacted:
            $ref: '#/components/schemas/RedactedReasoningContentValue'
    Base64ImageContentValue:
      type: object
      title: Base64 Image Content Value
      description: Base64-encoded image data with media type specification.
      required:
        - type
        - base64
        - mediaType
      properties:
        type:
          type: string
          enum:
            - base64
        base64:
          type: string
        mediaType:
          type: string
          enum:
            - png
            - jpeg
            - webp
            - gif
    UrlImageContentValue:
      type: object
      title: URL Image Content Value
      description: URL reference to an externally hosted image.
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - url
        url:
          type: string
    Base64HostedImageContentValue:
      type: object
      title: Base64 Hosted Image Content Value
      description: >-
        Base64-encoded image data with path and base64 hash, reference to a
        base64 image hosted on the platform.
      required:
        - type
        - path
        - base64Hash
      properties:
        type:
          type: string
          enum:
            - base64-hosted
        path:
          type: string
          minLength: 1
        base64Hash:
          type: string
          minLength: 1
    Base64PdfContentValue:
      type: object
      title: Base64 PDF Content Value
      description: Base64-encoded PDF document data.
      required:
        - type
        - base64
      properties:
        type:
          type: string
          enum:
            - base64
        base64:
          type: string
    UrlPdfContentValue:
      type: object
      title: URL PDF Content Value
      description: URL reference to an externally hosted PDF document.
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - url
        url:
          type: string
    Base64HostedPdfContentValue:
      type: object
      title: Base64 Hosted PDF Content Value
      description: >-
        Base64-encoded PDF document data with path and preview, reference to a
        base64 PDF hosted on the platform.
      required:
        - type
        - path
        - preview
      properties:
        type:
          type: string
          enum:
            - base64-hosted
        path:
          type: string
          minLength: 1
        preview:
          type: string
          minLength: 1
    ReasoningContentValue:
      type: object
      title: Reasoning Content Value
      description: >-
        LLM reasoning/thinking content with cryptographic signature for
        verification.
      required:
        - type
        - thinking
        - signature
      properties:
        type:
          type: string
          enum:
            - thinking
        thinking:
          type: string
        signature:
          type: string
    RedactedReasoningContentValue:
      type: object
      title: Redacted Reasoning Content Value
      description: Redacted/masked reasoning content for privacy-sensitive contexts.
      required:
        - type
        - data
      properties:
        type:
          type: string
          enum:
            - redacted
        data:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Workspace API key. Pass as `Authorization: Bearer <key>`.'

````