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

# List scores

> List scores with optional filters. Supports filtering by target (span, trace, session), score name, source, level, type, annotator, config name, and time range. All filter parameters accept comma-separated values for multi-value matching.

Ordering: use the `ordering` query param to sort results. Prefix a field name with `-` for descending. Default is `-created_at`. Valid fields: created_at, name, score_type, source, score_level, annotator_id, config_name, timestamp. The `timestamp` field sorts by the underlying target's timestamp (span/trace/session ingest time), which is not exposed as a separate field in the response.




## OpenAPI

````yaml GET /v3/scores
openapi: 3.0.3
info:
  title: Fiddler API - 2.0
  description: APIs to interact with Fiddler
  termsOfService: https://fiddler.ai/about/terms
  contact:
    email: support@fiddler.ai
  license:
    name: Proprietary
    url: '2.0'
  version: '2.0'
servers: []
security:
  - BearerAuth: []
tags:
  - name: access-key
    description: CRUD operations for API keys
  - name: span-v3
  - name: aggregation-invalidation-request-v3
    description: Endpoints related to retrieving aggregation invalidation requests
  - name: alert-rules-v3
    description: CRUD for Alert Rules, Summary, and Stats APIs
  - name: application-v3
  - name: attribute-v3
  - name: auth
    description: Authentication strategies and login flows
  - name: baseline-v3
    description: CRUD for baseline
  - name: catalog-v3
    description: >-
      Entity catalog provides paginated, searchable discovery of entity names
      (attribute keys, agent names, span types, span names, score names,
      evaluator config names) and their distinct values. Powered by ClickHouse
      materialized views — no worker or PostgreSQL dependency.
  - name: chart-annotation-v3
    description: Endpoints related to retrieving chart annotations
  - name: chart-v3
    description: CRUD for chart
  - name: queries-v3
    description: v3 queries API
  - name: configuration-v3
    description: CRUD for configurations
  - name: custom-metrics-v3
  - name: dimensionality-reduction-v3
  - name: environment-v3
    description: Endpoints related to environment management
  - name: evals
  - name: datasets
  - name: evaluation-v3
  - name: evaluator-v3
  - name: rule-evaluators-v3
  - name: experiment-v3
  - name: explainability-v3
  - name: llm_rca-v3
  - name: file-upload
    description: Endpoints related to file uploading.
  - name: fql-expressions-v3
    description: >
      Endpoints for listing FQL (Fiddler Query Language) functions available for
      GenAI custom metrics. Used by the frontend for autocomplete and signature
      hints in the FQL editor.
  - name: genai-alert-rules-v3
    description: CRUD API for GenAI Alert Rules
  - name: genai-custom-metrics-v3
    description: API for GenAI Custom Metrics
  - name: genai-metrics-v3
    description: >-
      Endpoints for pre-aggregated GenAI metrics. All metric data is
      pre-aggregated by an hourly ClickHouse refreshable materialized view; no
      real-time aggregation is performed at request time.
  - name: guardrails-api
    description: Endpoints related to retrieving Guardrails specific data
  - name: ingestion-v3
  - name: intercom-api
    description: Endpoints related to intercom APIs
  - name: jobs-v3
  - name: llm-gateway-v3
  - name: auth-login
  - name: auth-logout
  - name: mcp-client-setup-v3
    description: Endpoints for retrieving MCP client setup instructions.
  - name: metrics-v3
    description: Metrics endpoints
  - name: model-v3
  - name: dashboard-v3
  - name: model-deployment-v3
  - name: monitoring-summary-v3
  - name: histograms-v3
  - name: organization-roles-v3
    description: Update user org role
  - name: organization-settings-v3
    description: Update organization settings such as timezone, email configuration, etc.
  - name: pagerduty-api
    description: CRUD for Pagerduty services.
  - name: project-v3
  - name: project-roles-v3
    description: Project role assignment management
  - name: scores-v3
    description: Unified CRUD for scores and annotations
  - name: searchable-text-key-v3
    description: >-
      Manage the global searchable text keys table that controls which OTel
      attribute keys are routed to the full-text-searchable `ValueContent`
      column in the unified attributes table. Changes propagate to the backing
      ClickHouse dictionary within 1-2 minutes and affect all tenants.
  - name: segments-v3
  - name: semantic-mapping-v3
    description: >-
      Manage the global semantic name mappings table that maps raw OTel
      attribute keys to canonical semantic concepts. Changes propagate to the
      backing ClickHouse dictionary within 1-2 minutes and affect all tenants.
  - name: server-info-v3
    description: Endpoints related to retrieving server information
  - name: sessions-v3
    description: v3 session APIs
  - name: team-roles-v3
  - name: team-v3
  - name: traces-v3
    description: v3 trace api for monitoring
  - name: fetch-sessions-v3
    description: v3 fetch sessions api for monitoring
  - name: user-access-key
    description: >
      CRUD operations for user API keys. All endpoints are user-scoped — each
      user can only operate on their own API keys. No one including Org admins
      have access to other users' API keys.
  - name: users-v3
  - name: version-compatibility-v3
  - name: webhooks
externalDocs:
  url: https://docs.fiddler.ai
  description: Find out more about Fiddler
paths:
  /v3/scores:
    get:
      tags:
        - scores-v3
      summary: List scores
      description: >
        List scores with optional filters. Supports filtering by target (span,
        trace, session), score name, source, level, type, annotator, config
        name, and time range. All filter parameters accept comma-separated
        values for multi-value matching.


        Ordering: use the `ordering` query param to sort results. Prefix a field
        name with `-` for descending. Default is `-created_at`. Valid fields:
        created_at, name, score_type, source, score_level, annotator_id,
        config_name, timestamp. The `timestamp` field sorts by the underlying
        target's timestamp (span/trace/session ingest time), which is not
        exposed as a separate field in the response.
      operationId: listScores
      parameters:
        - name: application_id
          in: query
          description: Application UUID (required for auth scoping and partition pruning)
          required: true
          schema:
            type: string
            format: uuid
        - name: span_id
          in: query
          description: Filter by span ID(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: trace_id
          in: query
          description: Filter by trace ID(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: session_id
          in: query
          description: Filter by session ID(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: name
          in: query
          description: Filter by score name(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: source
          in: query
          description: >
            Filter by score source(s). Comma-separated for multiple values.
            Accepts evaluator for reading (POST restricts to non-evaluator
            sources).
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - evaluator
                - human
                - llm
                - code
          style: form
          explode: false
        - name: score_level
          in: query
          description: Filter by score level(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - span
                - trace
                - session
          style: form
          explode: false
        - name: score_type
          in: query
          description: Filter by score type(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - numeric
                - boolean
                - categorical
                - text
                - vector
          style: form
          explode: false
        - name: annotator_id
          in: query
          description: Filter by annotator ID(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: config_name
          in: query
          description: Filter by config name(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: score_ids
          in: query
          description: Filter by score UUID(s). Comma-separated for multiple values.
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
          style: form
          explode: false
        - name: start_time
          in: query
          description: >
            Scores with target timestamp >= start_time (ISO 8601). Filters on
            the underlying event's timestamp (span/trace/session ingest time),
            not the score's created_at.
          required: false
          schema:
            type: string
            format: date-time
        - name: end_time
          in: query
          description: >
            Scores with target timestamp < end_time (ISO 8601). Filters on the
            underlying event's timestamp (span/trace/session ingest time), not
            the score's created_at.
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Number of results per page (default 100, max 500)
          required: false
          schema:
            type: integer
            default: 100
            maximum: 500
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/ordering'
      responses:
        '200':
          description: Paginated list of scores
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: '#/components/schemas/ScoreResponse'
              example:
                data:
                  items:
                    - id: 660e8400-e29b-41d4-a716-446655440001
                      application_id: 550e8400-e29b-41d4-a716-446655440000
                      name: correctness
                      score_level: span
                      score_type: numeric
                      source: human
                      value: 0.95
                      created_at: '2026-06-15T10:30:00Z'
                  total: 1
                  page_size: 50
                  page_count: 1
                  page_index: 1
                  item_count: 1
                  offset: 0
                api_version: '3.0'
                kind: PAGINATED
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    offset:
      name: offset
      in: query
      description: Offset for the pagination
      required: false
      schema:
        type: integer
    ordering:
      name: ordering
      in: query
      description: >-
        Allows you to order results by any field. For desc order prefix field
        name with `-` and provide comman separated values for multiple fields
      required: false
      schema:
        type: string
  schemas:
    PaginatedApiResponse:
      type: object
      description: |
        Response object for paginated API responses.
      properties:
        api_version:
          type: string
          default: '3.0'
          enum:
            - '2.0'
            - '3.0'
          description: |
            API version of the response.
        kind:
          type: string
          default: PAGINATED
          enum:
            - PAGINATED
          description: |
            Type of response, indicating a paginated response.
        data:
          type: object
          properties:
            page_size:
              type: integer
              default: 10
              example: 10
              description: |
                Number of items per page in the response.
            item_count:
              type: integer
              default: 10
              example: 10
              description: |
                Number of items in the current page.
            total:
              type: integer
              example: 100
              default: 100
              description: |
                Total number of items across all pages.
            page_count:
              type: integer
              default: 10
              example: 10
              description: |
                Total number of pages.
            page_index:
              type: integer
              default: 1
              example: 1
              description: |
                Current page index.
            offset:
              type: integer
              default: 0
              example: 0
              description: |
                Offset of the first item in the current page.
    ScoreResponse:
      type: object
      description: Score resource returned by all read endpoints.
      properties:
        id:
          type: string
          format: uuid
          description: Unique score identifier
        application_id:
          type: string
          format: uuid
          description: Application this score belongs to
        name:
          type: string
          description: Score name (e.g. "correctness", "relevance")
        config_name:
          type: string
          nullable: true
          description: Configuration name. Defaults to name if not provided.
        config_id:
          type: integer
          nullable: true
          description: Configuration ID. Reserved for future use — currently always 0.
        score_level:
          type: string
          enum:
            - span
            - trace
            - session
          description: Target level inferred from which target ID was provided
        score_type:
          type: string
          enum:
            - numeric
            - boolean
            - categorical
            - text
            - vector
          description: >
            Type of score value. Determines which value field is populated. For
            vector-typed scores (created by evaluators, not via this API),
            value, label, and text are all null — the underlying vector data is
            not exposed through this endpoint. Consumers can filter these out
            using the score_type query parameter on the list endpoint.
        span_id:
          type: string
          nullable: true
          description: Target span ID (set when score_level is span)
        trace_id:
          type: string
          nullable: true
          description: Target trace ID (set when score_level is trace)
        session_id:
          type: string
          nullable: true
          description: Target session ID (set when score_level is session)
        source:
          type: string
          enum:
            - evaluator
            - human
            - llm
            - code
          description: Origin of this score
        annotator_id:
          type: string
          nullable: true
          description: >
            Annotator identifier. For source=human, populated from auth token.
            For source=llm or source=code, set from request.
        value:
          type: number
          format: double
          nullable: true
          description: Numeric value (set for numeric and boolean score types)
        label:
          type: string
          nullable: true
          description: Categorical label (set for categorical score type)
        text:
          type: string
          nullable: true
          description: Text value (set for text score type)
        reasoning:
          type: string
          nullable: true
          description: Optional reasoning or explanation for the score
        metadata:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Arbitrary key-value metadata (string to string map)
        status:
          type: string
          nullable: true
          description: Evaluator execution status (evaluator scores only)
        error_reason:
          type: string
          nullable: true
          description: Error classification (evaluator scores only)
        error_message:
          type: string
          nullable: true
          description: Error details (evaluator scores only)
        created_at:
          type: string
          format: date-time
          description: Timestamp when the score was created
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the most recent update
        timestamp:
          type: string
          format: date-time
          description: >
            Event timestamp — when the underlying span/trace/session occurred.
            Distinct from created_at (when this score record was written).
            Filterable via start_time/end_time; sortable via ordering=timestamp.
    ErrorResponse:
      type: object
      description: |
        Response object for errors returned by the API.
      properties:
        api_version:
          type: string
          default: '3.0'
          enum:
            - '2.0'
            - '3.0'
          description: |
            API version of the response.
        kind:
          type: string
          default: ERROR
          enum:
            - ERROR
          description: |
            Type of response, usually indicating an error.
        error:
          type: object
          properties:
            code:
              type: integer
              format: int32
              description: >
                Represents the code for this error, typically an HTTP response
                code.
              default: 400
              enum:
                - 400
                - 403
                - 404
                - 500
            message:
              type: string
              description: >
                A human-readable message providing more details about the error.
                If there are multiple errors, it will be the message for the
                first error.
              example: Resource Not Found
            errors:
              type: array
              description: >
                Container for additional information regarding the error,
                especially for multiple errors.
              items:
                type: object
                properties:
                  reason:
                    type: string
                    description: >
                      Unique identifier for this error, different from the error
                      code.
                    example: ResourceNotFoundException
                  message:
                    type: string
                    description: >
                      A human-readable message providing more details about the
                      error. If there is only one error, this field will match
                      error.message.
                    example: Resource Not Found
                  help:
                    type: string
                    description: >
                      Link to support or documentation providing more
                      information on the error.
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````