openapi: 3.0.3
info:
  title: Arize-Phoenix REST annotation_configs experiments API
  description: Schema for Arize-Phoenix REST API
  version: '1.0'
tags:
- name: experiments
paths:
  /v1/datasets/{dataset_id}/experiments:
    post:
      tags:
      - experiments
      summary: Create experiment on a dataset
      operationId: createExperiment
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          title: Dataset ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExperimentRequestBody'
      responses:
        '200':
          description: Experiment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateExperimentResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Dataset or DatasetVersion not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - experiments
      summary: List experiments by dataset
      description: Retrieve a paginated list of experiments for the specified dataset.
      operationId: listExperiments
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          title: Dataset ID
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
          description: Cursor for pagination (base64-encoded experiment ID)
          title: Cursor
        description: Cursor for pagination (base64-encoded experiment ID)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          exclusiveMinimum: 0
          description: The max number of experiments to return at a time.
          default: 50
          title: Limit
        description: The max number of experiments to return at a time.
      responses:
        '200':
          description: Paginated list of experiments for the dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExperimentsResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '422':
          content:
            text/plain:
              schema:
                type: string
          description: Unprocessable Entity
  /v1/experiments/{experiment_id}:
    get:
      tags:
      - experiments
      summary: Get experiment by ID
      operationId: getExperiment
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment Id
      responses:
        '200':
          description: Experiment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExperimentResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - experiments
      summary: Update an experiment by ID
      description: Partially update an experiment's name, description, and/or metadata. Only the fields included in the request body are changed; omitted fields are left as-is. Patching an ephemeral experiment refreshes its last-update timestamp, which extends the window before it is swept away.
      operationId: updateExperiment
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExperimentRequestBody'
      responses:
        '200':
          description: Experiment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateExperimentResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          content:
            text/plain:
              schema:
                type: string
          description: Invalid experiment ID or request body
    delete:
      tags:
      - experiments
      summary: Delete experiment by ID
      operationId: deleteExperiment
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment Id
      - name: delete_project
        in: query
        required: false
        schema:
          type: boolean
          description: If true, also delete the project associated with the experiment that contains traces and spans for the experiment tasks.
          default: false
          title: Delete Project
        description: If true, also delete the project associated with the experiment that contains traces and spans for the experiment tasks.
      responses:
        '204':
          description: Experiment deleted successfully
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/experiments/{experiment_id}/incomplete-runs:
    get:
      tags:
      - experiments
      summary: Get incomplete runs for an experiment
      description: "Get runs that need to be completed for this experiment.\n\nReturns all incomplete runs, including both missing runs (not yet attempted)\nand failed runs (attempted but have errors).\n\nArgs:\n    experiment_id: The ID of the experiment\n    cursor: Cursor for pagination\n    limit: Maximum number of results to return\n\nReturns:\n    Paginated list of incomplete runs grouped by dataset example,\n    with repetition numbers that need to be run"
      operationId: getIncompleteExperimentRuns
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment Id
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
          description: Cursor for pagination
          title: Cursor
        description: Cursor for pagination
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          exclusiveMinimum: 0
          description: Maximum number of examples with incomplete runs to return
          default: 50
          title: Limit
        description: Maximum number of examples with incomplete runs to return
      responses:
        '200':
          description: Incomplete runs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIncompleteExperimentRunsResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          content:
            text/plain:
              schema:
                type: string
          description: Invalid cursor format
  /v1/experiments/{experiment_id}/json:
    get:
      tags:
      - experiments
      summary: Download experiment runs as a JSON file
      operationId: getExperimentJSON
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment ID
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/experiments/{experiment_id}/csv:
    get:
      tags:
      - experiments
      summary: Download experiment runs as a CSV file
      operationId: getExperimentCSV
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
            text/csv:
              schema:
                type: string
                contentMediaType: text/csv
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/experiments/{experiment_id}/runs:
    post:
      tags:
      - experiments
      summary: Create run for an experiment
      operationId: createExperimentRun
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExperimentRunRequestBody'
      responses:
        '200':
          description: Experiment run created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateExperimentRunResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment or dataset example not found
        '409':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment run already exists with a successful result and cannot be updated
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - experiments
      summary: List runs for an experiment
      description: Retrieve a paginated list of runs for an experiment
      operationId: listExperimentRuns
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment Id
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
          description: Cursor for pagination (base64-encoded experiment run ID)
          title: Cursor
        description: Cursor for pagination (base64-encoded experiment run ID)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          exclusiveMinimum: 0
          nullable: true
          description: The max number of experiment runs to return at a time. If not specified, returns all results.
          title: Limit
        description: The max number of experiment runs to return at a time. If not specified, returns all results.
      responses:
        '200':
          description: Experiment runs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExperimentRunsResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          content:
            text/plain:
              schema:
                type: string
          description: Invalid cursor format
  /v1/experiments/{experiment_id}/incomplete-evaluations:
    get:
      tags:
      - experiments
      summary: Get incomplete evaluations for an experiment
      description: "Get experiment runs that have incomplete evaluations.\n\nReturns runs with:\n- Missing evaluations (evaluator has not been run)\n- Failed evaluations (evaluator ran but has errors)\n\nArgs:\n    experiment_id: The ID of the experiment\n    evaluation_name: List of evaluation names to check (required, at least one)\n    cursor: Cursor for pagination\n    limit: Maximum number of results to return\n\nReturns:\n    Paginated list of runs with incomplete evaluations"
      operationId: getIncompleteExperimentEvaluations
      parameters:
      - name: experiment_id
        in: path
        required: true
        schema:
          type: string
          title: Experiment Id
      - name: evaluation_name
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Evaluation names to check
          default: []
          title: Evaluation Name
        description: Evaluation names to check
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          nullable: true
          description: Cursor for pagination
          title: Cursor
        description: Cursor for pagination
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          exclusiveMinimum: 0
          description: Maximum number of runs with incomplete evaluations to return
          default: 50
          title: Limit
        description: Maximum number of runs with incomplete evaluations to return
      responses:
        '200':
          description: Incomplete evaluations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIncompleteEvaluationsResponseBody'
        '403':
          content:
            text/plain:
              schema:
                type: string
          description: Forbidden
        '400':
          content:
            text/plain:
              schema:
                type: string
          description: No evaluator names provided
        '404':
          content:
            text/plain:
              schema:
                type: string
          description: Experiment not found
        '422':
          content:
            text/plain:
              schema:
                type: string
          description: Invalid cursor format
  /v1/experiment_evaluations:
    post:
      tags:
      - experiments
      summary: Create or update evaluation for an experiment run
      operationId: upsertExperimentEvaluation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertExperimentEvaluationRequestBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertExperimentEvaluationResponseBody'
        '403':
          description: Forbidden
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Experiment run not found
          content:
            text/plain:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ExperimentEvaluationResult:
      properties:
        label:
          type: string
          nullable: true
          title: Label
          description: The label assigned by the evaluation
        score:
          type: number
          nullable: true
          title: Score
          description: The score assigned by the evaluation
        explanation:
          type: string
          nullable: true
          title: Explanation
          description: Explanation of the evaluation result
      type: object
      title: ExperimentEvaluationResult
    CreateExperimentRunResponseBodyData:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the newly created experiment run
      type: object
      required:
      - id
      title: CreateExperimentRunResponseBodyData
    Experiment:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the experiment
        dataset_id:
          type: string
          title: Dataset Id
          description: The ID of the dataset associated with the experiment
        dataset_version_id:
          type: string
          title: Dataset Version Id
          description: The ID of the dataset version associated with the experiment
        name:
          type: string
          title: Name
          description: The name of the experiment
        description:
          type: string
          nullable: true
          title: Description
          description: The description of the experiment
        repetitions:
          type: integer
          exclusiveMinimum: 0.0
          title: Repetitions
          description: Number of times the experiment is repeated
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Metadata of the experiment
        project_name:
          type: string
          nullable: true
          title: Project Name
          description: The name of the project associated with the experiment
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The creation timestamp of the experiment
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: The last update timestamp of the experiment
        example_count:
          type: integer
          title: Example Count
          description: Number of examples in the experiment
        successful_run_count:
          type: integer
          title: Successful Run Count
          description: Number of successful runs in the experiment
        failed_run_count:
          type: integer
          title: Failed Run Count
          description: Number of failed runs in the experiment
        missing_run_count:
          type: integer
          title: Missing Run Count
          description: Number of missing (not yet executed) runs in the experiment
      type: object
      required:
      - id
      - dataset_id
      - dataset_version_id
      - name
      - description
      - repetitions
      - metadata
      - project_name
      - created_at
      - updated_at
      - example_count
      - successful_run_count
      - failed_run_count
      - missing_run_count
      title: Experiment
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IncompleteExperimentEvaluation:
      properties:
        experiment_run:
          $ref: '#/components/schemas/ExperimentRun'
          description: The experiment run
        dataset_example:
          $ref: '#/components/schemas/DatasetExample'
          description: The dataset example
        evaluation_names:
          items:
            type: string
          type: array
          title: Evaluation Names
          description: List of evaluation names that are incomplete (either missing or failed)
      type: object
      required:
      - experiment_run
      - dataset_example
      - evaluation_names
      title: IncompleteExperimentEvaluation
      description: Information about an experiment run with incomplete evaluations
    CreateExperimentResponseBody:
      properties:
        data:
          $ref: '#/components/schemas/Experiment'
      type: object
      required:
      - data
      title: CreateExperimentResponseBody
    ExperimentRun:
      properties:
        dataset_example_id:
          type: string
          title: Dataset Example Id
          description: The ID of the dataset example used in the experiment run
        output:
          title: Output
          description: The output of the experiment task
        repetition_number:
          type: integer
          exclusiveMinimum: 0.0
          title: Repetition Number
          description: The repetition number of the experiment run
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: The start time of the experiment run
        end_time:
          type: string
          format: date-time
          title: End Time
          description: The end time of the experiment run
        trace_id:
          type: string
          nullable: true
          title: Trace Id
          description: The ID of the corresponding trace (if one exists)
        error:
          type: string
          nullable: true
          title: Error
          description: Optional error message if the experiment run encountered an error
        id:
          type: string
          title: Id
          description: The ID of the experiment run
        experiment_id:
          type: string
          title: Experiment Id
          description: The ID of the experiment
      type: object
      required:
      - dataset_example_id
      - output
      - repetition_number
      - start_time
      - end_time
      - id
      - experiment_id
      title: ExperimentRun
    ListExperimentsResponseBody:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Experiment'
          type: array
          title: Data
        next_cursor:
          type: string
          nullable: true
          title: Next Cursor
      type: object
      required:
      - data
      - next_cursor
      title: ListExperimentsResponseBody
    CreateExperimentRunResponseBody:
      properties:
        data:
          $ref: '#/components/schemas/CreateExperimentRunResponseBodyData'
      type: object
      required:
      - data
      title: CreateExperimentRunResponseBody
    UpdateExperimentRequestBody:
      properties:
        name:
          type: string
          nullable: true
          title: Name
          description: New name for the experiment (null is rejected; name is required)
        description:
          type: string
          nullable: true
          title: Description
          description: New description for the experiment (null clears the description)
        metadata:
          additionalProperties: true
          type: object
          nullable: true
          title: Metadata
          description: New metadata object for the experiment (replaces the existing metadata as a whole; null is rejected)
      type: object
      title: UpdateExperimentRequestBody
      description: Fields to update on an experiment. Omit a field to leave it unchanged.
    ListExperimentRunsResponseBody:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ExperimentRun'
          type: array
          title: Data
        next_cursor:
          type: string
          nullable: true
          title: Next Cursor
      type: object
      required:
      - data
      - next_cursor
      title: ListExperimentRunsResponseBody
    IncompleteExperimentRun:
      properties:
        dataset_example:
          $ref: '#/components/schemas/DatasetExample'
          description: The dataset example
        repetition_numbers:
          items:
            type: integer
          type: array
          title: Repetition Numbers
          description: List of repetition numbers that need to be run
      type: object
      required:
      - dataset_example
      - repetition_numbers
      title: IncompleteExperimentRun
      description: Information about incomplete runs for a dataset example
    UpdateExperimentResponseBody:
      properties:
        data:
          $ref: '#/components/schemas/Experiment'
      type: object
      required:
      - data
      title: UpdateExperimentResponseBody
    CreateExperimentRequestBody:
      properties:
        name:
          type: string
          nullable: true
          title: Name
          description: Name of the experiment (if omitted, a random name will be generated)
        description:
          type: string
          nullable: true
          title: Description
          description: An optional description of the experiment
        metadata:
          additionalProperties: true
          type: object
          nullable: true
          title: Metadata
          description: Metadata for the experiment
        version_id:
          type: string
          nullable: true
          title: Version Id
          description: ID of the dataset version over which the experiment will be run (if omitted, the latest version will be used)
        splits:
          items:
            type: string
          type: array
          nullable: true
          title: Splits
          description: List of dataset split identifiers (GlobalIDs or names) to filter by
        repetitions:
          type: integer
          title: Repetitions
          description: Number of times the experiment should be repeated for each example
          default: 1
      type: object
      title: CreateExperimentRequestBody
      description: Details of the experiment to be created
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UpsertExperimentEvaluationRequestBody:
      properties:
        experiment_run_id:
          type: string
          title: Experiment Run Id
          description: The ID of the experiment run being evaluated
        name:
          type: string
          title: Name
          description: The name of the evaluation
        annotator_kind:
          type: string
          enum:
          - LLM
          - CODE
          - HUMAN
          title: Annotator Kind
          description: The kind of annotator used for the evaluation
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: The start time of the evaluation in ISO format
        end_time:
          type: string
          format: date-time
          title: End Time
          description: The end time of the evaluation in ISO format
        result:
          $ref: '#/components/schemas/ExperimentEvaluationResult'
          nullable: true
          description: The result of the evaluation. Either result or error must be provided.
        error:
          type: string
          nullable: true
          title: Error
          description: Error message if the evaluation encountered an error. Either result or error must be provided.
        metadata:
          additionalProperties: true
          type: object
          nullable: true
          title: Metadata
          description: Metadata for the evaluation
        trace_id:
          type: string
          nullable: true
          title: Trace Id
          description: Optional trace ID for tracking
      type: object
      required:
      - experiment_run_id
      - name
      - annotator_kind
      - start_time
      - end_time
      title: UpsertExperimentEvaluationRequestBody
    CreateExperimentRunRequestBody:
      properties:
        dataset_example_id:
          type: string
          title: Dataset Example Id
          description: The ID of the dataset example used in the experiment run
        output:
          title: Output
          description: The output of the experiment task
        repetition_number:
          type: integer
          exclusiveMinimum: 0.0
          title: Repetition Number
          description: The repetition number of the experiment run
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: The start time of the experiment run
        end_time:
          type: string
          format: date-time
          title: End Time
          description: The end time of the experiment run
        trace_id:
          type: string
          nullable: true
          title: Trace Id
          description: The ID of the corresponding trace (if one exists)
        error:
          type: string
          nullable: true
          title: Error
          description: Optional error message if the experiment run encountered an error
      type: object
      required:
      - dataset_example_id
      - output
      - repetition_number
      - start_time
      - end_time
      title: CreateExperimentRunRequestBody
    GetIncompleteExperimentRunsResponseBody:
      properties:
        data:
          items:
            $ref: '#/components/schemas/IncompleteExperimentRun'
          type: array
          title: Data
        next_cursor:
          type: string
          nullable: true
          title: Next Cursor
      type: object
      required:
      - data
      - next_cursor
      title: GetIncompleteExperimentRunsResponseBody
    UpsertExperimentEvaluationResponseBodyData:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the upserted experiment evaluation
      type: object
      required:
      - id
      title: UpsertExperimentEvaluationResponseBodyData
    GetExperimentResponseBody:
      properties:
        data:
          $ref: '#/components/schemas/Experiment'
      type: object
      required:
      - data
      title: GetExperimentResponseBody
    UpsertExperimentEvaluationResponseBody:
      properties:
        data:
          $ref: '#/components/schemas/UpsertExperimentEvaluationResponseBodyData'
      type: object
      required:
      - data
      title: UpsertExperimentEvaluationResponseBody
    GetIncompleteEvaluationsResponseBody:
      properties:
        data:
          items:
            $ref: '#/components/schemas/IncompleteExperimentEvaluation'
          type: array
          title: Data
        next_cursor:
          type: string
          nullable: true
          title: Next Cursor
      type: object
      required:
      - data
      - next_cursor
      title: GetIncompleteEvaluationsResponseBody
    DatasetExample:
      properties:
        id:
          type: string
          title: Id
        node_id:
          type: string
          title: Node Id
        input:
          additionalProperties: true
          type: object
          title: Input
        output:
          additionalProperties: true
          type: object
          title: Output
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - node_id
      - input
      - output
      - metadata
      - updated_at
      title: DatasetExample