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

# Report DSPy optimizer steps

> Report the steps of a DSPy optimizer run against an experiment, so the run's progress and scores show up in the app. Send the steps as an array; the optimizer typically posts each batch as it finishes. Bodies up to 20MB are accepted.



## OpenAPI

````yaml POST /api/dspy/log_steps
openapi: 3.1.0
info:
  title: LangWatch API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/dspy/log_steps:
    post:
      tags:
        - Experiments
      summary: Report DSPy optimizer steps
      description: >-
        Report the steps of a DSPy optimizer run against an experiment, so the
        run's progress and scores show up in the app. Send the steps as an
        array; the optimizer typically posts each batch as it finishes. Bodies
        up to 20MB are accepted.
      operationId: postApiDspyLog_steps
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    properties:
                      run_id:
                        type: string
                      workflow_version_id:
                        type: string
                        nullable: true
                      index:
                        type: string
                      score:
                        type: number
                      label:
                        type: string
                      optimizer:
                        type: object
                        properties:
                          name:
                            type: string
                          parameters:
                            type: object
                            additionalProperties: {}
                        required:
                          - name
                          - parameters
                        additionalProperties: false
                      predictors:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            predictor:
                              allOf:
                                - type: object
                                  properties:
                                    __class__:
                                      type: string
                                - type: object
                                  additionalProperties: {}
                          required:
                            - name
                            - predictor
                          additionalProperties: false
                    required:
                      - run_id
                      - index
                      - score
                      - label
                      - optimizer
                      - predictors
                  - type: object
                    properties:
                      experiment_id:
                        type: string
                        nullable: true
                      experiment_slug:
                        type: string
                        nullable: true
                      timestamps:
                        type: object
                        properties:
                          created_at:
                            type: number
                        required:
                          - created_at
                        additionalProperties: false
                      examples:
                        type: array
                        items:
                          type: object
                          properties:
                            example:
                              allOf:
                                - type: object
                                  properties:
                                    __class__:
                                      type: string
                                - type: object
                                  additionalProperties: {}
                            pred:
                              allOf:
                                - type: object
                                  properties:
                                    __class__:
                                      type: string
                                - type: object
                                  additionalProperties: {}
                            score:
                              type: number
                            trace:
                              type: array
                              items:
                                type: object
                                properties:
                                  input:
                                    allOf:
                                      - type: object
                                        properties:
                                          __class__:
                                            type: string
                                      - type: object
                                        additionalProperties: {}
                                  pred:
                                    allOf:
                                      - type: object
                                        properties:
                                          __class__:
                                            type: string
                                      - type: object
                                        additionalProperties: {}
                                required:
                                  - input
                                  - pred
                                additionalProperties: false
                              nullable: true
                          required:
                            - example
                            - pred
                            - score
                          additionalProperties: false
                      llm_calls:
                        type: array
                        items:
                          type: object
                          properties:
                            __class__:
                              type: string
                            response:
                              allOf:
                                - type: object
                                  properties:
                                    __class__:
                                      type: string
                                - type: object
                                  additionalProperties: {}
                            model:
                              type: string
                              nullable: true
                            prompt_tokens:
                              type: number
                              nullable: true
                            completion_tokens:
                              type: number
                              nullable: true
                            cost:
                              type: number
                              nullable: true
                          required:
                            - __class__
                            - response
                          additionalProperties: false
                    required:
                      - timestamps
                      - examples
                      - llm_calls
      responses:
        '200':
          description: Every step in the batch was recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable confirmation
                required:
                  - message
        '400':
          description: >-
            The body was not valid JSON, failed validation, or carried
            timestamps in seconds rather than milliseconds
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Set when the request was rejected before validation
                  error:
                    type: string
                    description: Set when the body parsed and then failed validation
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '403':
          description: The API key lacks experiments:manage
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Stable failure code; branch on this
                  message:
                    type: string
                  fault:
                    type: string
                    description: >-
                      Who the failure is attributable to: customer, platform,
                      provider
                  tips:
                    type: array
                    items:
                      type: string
                  docsUrl:
                    type: string
                required:
                  - error
                additionalProperties: true
        '500':
          description: >-
            A step could not be stored. The cause is on our side and is logged
            with the run and step ids; retrying the batch is safe.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Set when the request was rejected before validation
                  error:
                    type: string
                    description: Set when the body parsed and then failed validation
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        Project API key for sending traces and accessing project-scoped
        resources. Format: sk-lw-... (no underscore). Obtain one by creating a
        project via the Admin API or the LangWatch UI.

````