> ## 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.

# Update a score

> Partially update a score. Only value fields (value, label, text, reasoning, metadata) can be updated. Identity and structural fields (name, score_type, source, targets) cannot be changed — create a new score instead. Returns 403 if source is evaluator.




## OpenAPI

````yaml PATCH /v3/scores/{score_id}
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) 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: 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/{score_id}:
    patch:
      tags:
        - scores-v3
      summary: Update a score
      description: >
        Partially update a score. Only value fields (value, label, text,
        reasoning, metadata) can be updated. Identity and structural fields
        (name, score_type, source, targets) cannot be changed — create a new
        score instead. Returns 403 if source is evaluator.
      operationId: updateScore
      parameters:
        - name: score_id
          in: path
          description: Score UUID
          required: true
          schema:
            type: string
            format: uuid
        - name: application_id
          in: query
          description: Application UUID (required for auth scoping and partition pruning)
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScoreRequest'
            example:
              value: 0.85
              reasoning: Revised assessment after further review
      responses:
        '200':
          description: Score updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ScoreResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    UpdateScoreRequest:
      type: object
      description: >
        Request body for partially updating a score. Only provided fields are
        updated. Identity and structural fields (name, score_type, source,
        targets, annotator_id) cannot be changed — annotator_id is immutable
        after creation; create a new score to reassign.
      properties:
        value:
          type: number
          format: double
          nullable: true
          description: Updated numeric value
        label:
          type: string
          nullable: true
          description: Updated categorical label
        text:
          type: string
          nullable: true
          maxLength: 65536
          description: Updated text content
        reasoning:
          type: string
          nullable: true
          description: Updated reasoning
        metadata:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Updated metadata (replaces entire map)
      additionalProperties: false
    ApiResponse:
      type: object
      description: |
        Response object for standard API responses.
      properties:
        api_version:
          type: string
          default: '3.0'
          enum:
            - '2.0'
            - '3.0'
          description: |
            API version.
        kind:
          type: string
          default: NORMAL
          enum:
            - NORMAL
          description: |
            Type of response, indicating a normal response.
    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'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '404':
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '422':
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '429':
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Limit:
          schema:
            type: string
          description: Rate limit policy
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests in current window
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when the rate limit resets
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````