Scale AI Evaluation Items API

openapi: 3.2.0
info:
  title: EGP API V5 Evaluation Items API
  description: This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
- url: https://api.egp.scale.com
security: []
tags:
- name: Evaluation Items
paths:
  /v5/evaluation-items/export:
    post:
      tags:
      - Evaluation Items
      summary: Export evaluation items to a file
      description: 'Export all evaluation items for a single evaluation as a downloadable file.


        The evaluation is specified by `evaluation_id` in the request body. `export_format`

        selects CSV, JSON, or JSONL; for CSV the per-item `data` and `files` fields are

        flattened into individual columns and metric-like result columns are expanded.

        `export_method` controls delivery: `direct` returns the file contents inline in the

        response, while `signed_url` uploads the file to object storage and returns a

        pre-signed download URL. Requesting `signed_url` in an environment where object

        storage is not configured fails with a 501, so use `direct` there instead. Set

        `include_archived=true` to include archived items in the export. This endpoint reads

        items only and does not modify the evaluation.'
      operationId: POST-V5-/v5/evaluation-items/export
      parameters:
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluationItemsExportRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationItemsExportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/evaluation-items/export-evaluation-items-to-a-file
  /v5/evaluation-items/{evaluation_item_id}:
    get:
      tags:
      - Evaluation Items
      summary: Get a single evaluation item
      description: 'Retrieve a single evaluation item by its ID within the caller''s account.


        By default only non-archived items are returned; pass `include_archived=true` to

        also retrieve an item that has been archived. The response merges the item''s cached

        task results into its `data` field and exposes a `task_errors` map keyed by task

        alias, so a task that failed on this item surfaces as an entry there rather than as a

        request error. Use this to inspect one item''s input data and per-task results; to page

        through many items, use the list endpoint instead. The request fails if no item with

        the given ID exists in the caller''s account.'
      operationId: GET-V5-/v5/evaluation-items/evaluation_item_id
      parameters:
      - name: evaluation_item_id
        in: path
        required: true
        schema:
          type: string
          title: Evaluation Item Id
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationItem'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/evaluation-items/get-a-single-evaluation-item
  /v5/evaluation-items:
    get:
      tags:
      - Evaluation Items
      summary: List and filter evaluation items
      description: 'Return a paginated list of evaluation items belonging to the caller''s account.


        Pass `evaluation_id` to restrict the results to a single evaluation''s items. The

        `completion_status` filter selects items by whether any of their tasks errored:

        `failed` returns only items that have task errors, `passed` returns only items with no

        task errors, and `all` (or omitting the parameter) returns every item. Archived items

        are excluded unless `include_archived=true`. Each returned item has its cached task

        results merged into `data` and its errors exposed in `task_errors`, identically to the

        single-item endpoint.'
      operationId: GET-V5-/v5/evaluation-items
      parameters:
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      - name: evaluation_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Evaluation Id
      - name: completion_status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CompletionStatus'
          - type: 'null'
          description: Filter items by completion status. Pass 'failed' to return only items with errors, 'passed' for items without errors. Pass 'all' or omit to return all items.
          title: Completion Status
        description: Filter items by completion status. Pass 'failed' to return only items with errors, 'passed' for items without errors. Pass 'all' or omit to return all items.
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_EvaluationItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/evaluation-items/list-and-filter-evaluation-items
components:
  schemas:
    EvaluationItemsExportResponse:
      properties:
        filename:
          type: string
          title: Filename
          description: The name of the exported file
        signed_url:
          title: Signed Url
          description: Pre-signed URL to download the file from object storage, if applicable
          type: string
        content:
          title: Content
          description: The raw file content as bytes, used when direct download is enabled
          type: string
          contentMediaType: application/octet-stream
      type: object
      required:
      - filename
      title: EvaluationItemsExportResponse
      description: 'Response model for exporting evaluation items.

        This class represents the response when users export evaluation items.

        It contains either a signed URL to download the exported data from object storage,

        or the actual content bytes when direct download is used (in environments where object storage is not configured).'
    IdentityType:
      type: string
      enum:
      - user
      - service_account
      title: IdentityType
    EvaluationItemsExportRequest:
      properties:
        export_method:
          $ref: '#/components/schemas/ExportMethod'
          description: The method for exporting evaluation items. `signed_url` returns a pre-signed URL, while `direct` returns the raw content.
          default: direct
        export_format:
          $ref: '#/components/schemas/ExportFormat'
          description: The format of the exported evaluation items. `json` returns a single JSON array, while `jsonl` returns one JSON object per line.
          default: csv
        evaluation_id:
          type: string
          title: Evaluation Id
          description: The ID of the evaluation to export items from.
        include_archived:
          type: boolean
          title: Include Archived
          description: If true, include archived evaluation items in the export.
          default: false
      type: object
      required:
      - evaluation_id
      title: EvaluationItemsExportRequest
    CompletionStatus:
      type: string
      enum:
      - failed
      - passed
      - all
      title: CompletionStatus
      description: Filter for evaluation item completion status based on task errors.
    PaginatedList_EvaluationItem_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/EvaluationItem'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    ExportMethod:
      type: string
      enum:
      - signed_url
      - direct
      title: ExportMethod
    ExportFormat:
      type: string
      enum:
      - json
      - jsonl
      - csv
      title: ExportFormat
    EvaluationItem:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the entity.
        object:
          type: string
          const: evaluation.item
          title: Object
          default: evaluation.item
        created_by:
          $ref: '#/components/schemas/Identity'
          description: The identity that created the entity.
        evaluation_id:
          type: string
          title: Evaluation Id
        dataset_item_id:
          type: string
          title: Dataset Item Id
        dataset_item_version_num:
          title: Dataset Item Version Num
          type: integer
        data:
          additionalProperties: true
          type: object
          title: Data
        files:
          title: Files
          additionalProperties:
            type: string
          type: object
        task_errors:
          title: Task Errors
          description: Map of task alias to error info.
          additionalProperties:
            $ref: '#/components/schemas/TaskError'
          type: object
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the entity was created in ISO format.
        archived_at:
          title: Archived At
          description: The date and time when the entity was archived in ISO format.
          type: string
          format: date-time
      type: object
      required:
      - created_by
      - evaluation_id
      - data
      - id
      - created_at
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          title: Error Type
          type: string
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Identity:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: identity
          title: Object
          default: identity
        type:
          $ref: '#/components/schemas/IdentityType'
      type: object
      required:
      - id
      - type
      title: Identity
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    TaskError:
      properties:
        type:
          type: string
          title: Type
          description: Error type/category
        message:
          type: string
          title: Message
          description: Error message
      type: object
      required:
      - type
      - message
      title: TaskError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-assembled-from: Per-operation OpenAPI fragments embedded verbatim in docs.gp.scale.com reference pages; source spec https://api.sgp.scale.com/openapi-versions/v5/openapi.json (404 when assembled)