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

# List span or trace assessments

> Return the assessments attached to a given span or trace.

Results are scoped to the caller's account. At least one of span_id or
trace_id must be supplied as a query parameter, and a request providing
neither returns 400. Filtering by trace_id returns assessments across every
span of that trace, whereas span_id returns only that span's assessments, and
supplying both restricts the result to that span within that trace. An
optional assessment_type narrows the results to a single type. Use the
get-by-id endpoint when you already have a specific assessment id.

``x-project-id`` narrows the result to assessments on traces whose root span carries
that project, when ``PROJECT_SCOPED_SPAN_LISTING`` is on for the account.



## OpenAPI

````yaml /openapi/v5.yaml get /v5/span-assessments
openapi: 3.1.0
info:
  title: EGP API V5
  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: []
paths:
  /v5/span-assessments:
    get:
      tags:
        - Span Assessment
      summary: List span or trace assessments
      description: >-
        Return the assessments attached to a given span or trace.


        Results are scoped to the caller's account. At least one of span_id or

        trace_id must be supplied as a query parameter, and a request providing

        neither returns 400. Filtering by trace_id returns assessments across
        every

        span of that trace, whereas span_id returns only that span's
        assessments, and

        supplying both restricts the result to that span within that trace. An

        optional assessment_type narrows the results to a single type. Use the

        get-by-id endpoint when you already have a specific assessment id.


        ``x-project-id`` narrows the result to assessments on traces whose root
        span carries

        that project, when ``PROJECT_SCOPED_SPAN_LISTING`` is on for the
        account.
      operationId: GET-V5-/v5/span-assessments
      parameters:
        - name: span_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter by span ID. Either span_id or trace_id must be provided as
              a query parameter.
            title: Span Id
          description: >-
            Filter by span ID. Either span_id or trace_id must be provided as a
            query parameter.
        - name: trace_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter by trace ID. Either span_id or trace_id must be provided as
              a query parameter.
            title: Trace Id
          description: >-
            Filter by trace ID. Either span_id or trace_id must be provided as a
            query parameter.
        - name: assessment_type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/AssessmentType'
              - type: 'null'
            description: Filter by assessment type
            title: Assessment Type
          description: Filter by assessment type
        - name: x-selected-account-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Account ID Header
        - name: x-project-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Project ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIList_SpanAssessment_'
        '400':
          description: >-
            The request carried a value this API or the tracing service
            rejected, such as a search term breaking a documented rule or a
            malformed pagination cursor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanReadErrorResponse'
        '422':
          description: >-
            A malformed request returns the validation error shape, one entry
            per offending field. A request this API refuses returns only detail,
            as when x-project-id is sent for an account whose tracing backend
            cannot apply the project scope.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/HTTPValidationError'
                  - $ref: '#/components/schemas/SpanReadErrorResponse'
        '503':
          description: >-
            The configured tracing read backend is unavailable. Known service
            configuration failures include a stable error_code; other failures
            return only detail.
          headers:
            x-correlation-id:
              description: Correlation ID for this request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpanReadErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AssessmentType:
      type: string
      enum:
        - comment
        - rating
        - approval
        - rubric
        - metadata
        - overwrite
      title: AssessmentType
      description: Types of assessments that can be provided
    APIList_SpanAssessment_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/SpanAssessment'
          type: array
          title: Items
      type: object
      required:
        - items
    SpanReadErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: A user-safe explanation of why the tracing read failed.
        error_code:
          anyOf:
            - type: string
              const: TRACES_SERVICE_CONFIGURATION_ERROR
            - type: 'null'
          title: Error Code
          description: >-
            Stable classification for a known EGP-to-tracing-service
            configuration failure. Omitted when the downstream failure is not
            safely classifiable.
      type: object
      required:
        - detail
      title: SpanReadErrorResponse
      description: Safe public error body for a tracing read that could not be completed.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SpanAssessment:
      properties:
        object:
          type: string
          const: span.assessment
          title: Object
          default: span.assessment
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
          description: Raw text feedback
        rating:
          anyOf:
            - type: integer
              maximum: 5
              minimum: 1
            - type: 'null'
          title: Rating
          description: Numerical rating (1-5)
        approval:
          anyOf:
            - $ref: '#/components/schemas/ApprovalStatus'
            - type: 'null'
          description: Approval status (approved/rejected)
        rubric:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Rubric
          description: Rule key-value pairs for rubric evaluation
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Arbitrary JSON object for additional data
        overwrite:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Overwrite
          description: User corrections to span output
        assessment_id:
          type: string
          title: Assessment Id
          description: Unique identifier for the assessment
        trace_id:
          type: string
          title: Trace Id
          description: The trace this assessment is attached to
        span_id:
          type: string
          title: Span Id
          description: The span this assessment is attached to
        created_by:
          type: string
          title: Created By
          description: User who submitted the assessment
        assessment_type:
          $ref: '#/components/schemas/AssessmentType'
          description: Type of assessment
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Id
          description: Account this assessment belongs to
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: When this assessment was created
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: When this assessment was last updated
      additionalProperties: true
      type: object
      required:
        - assessment_id
        - trace_id
        - span_id
        - created_by
        - assessment_type
      description: Response model for span assessment
    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
          additionalProperties: true
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ApprovalStatus:
      type: string
      enum:
        - approved
        - rejected
      title: ApprovalStatus
      description: Status options for approval assessments
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````