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

# Score one or more traces with a scorer (on-demand)

> Scores historical traces/spans with a scorer from the catalog (`public.scorer_options`), fire-and-forget. Send `scorerType` = the catalog `scorer_type_id` (e.g. "tone", "bias"). LLM scorers require `X-Organization-Id`. Poll GET /api/scores/scorer/<scorerId> for results.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/score-trace
openapi: 3.1.0
info:
  title: Sidenet API
  version: 1.0.0
  description: >-
    Custom HTTP endpoints exposed by the Sidenet Mastra server. All routes
    require a bearer token and resolve org context from the API key (or the
    `X-Organization-Id` header). This reference is generated from the live route
    definitions in `src/mastra/routes`.
servers:
  - url: ''
security:
  - bearerAuth: []
paths:
  /v1/score-trace:
    servers:
      - url: /
    post:
      tags:
        - Custom
      summary: Score one or more traces with a scorer (on-demand)
      description: >-
        Scores historical traces/spans with a scorer from the catalog
        (`public.scorer_options`), fire-and-forget. Send `scorerType` = the
        catalog `scorer_type_id` (e.g. "tone", "bias"). LLM scorers require
        `X-Organization-Id`. Poll GET /api/scores/scorer/<scorerId> for results.
      parameters:
        - name: X-Organization-Id
          in: header
          required: false
          description: Organization ID (required for LLM scorers).
          schema:
            type: string
        - name: X-User-Id
          in: header
          required: false
          schema:
            type: string
          description: >-
            End-user identity for the request; user-scoped data (threads,
            memory) resolves to `{orgId}_{userId}`. Required by endpoints that
            read or write user-scoped resources. A `userId` query param (or body
            field, where documented) is accepted as a fallback.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - scorerType
                - targets
              properties:
                scorerType:
                  type: string
                  description: >-
                    Catalog scorer_type_id from public.scorer_options (e.g.
                    "tone", "bias", "completeness").
                targets:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                      - traceId
                    properties:
                      traceId:
                        type: string
                      spanId:
                        type: string
      responses:
        '200':
          description: Scoring started
        '400':
          description: Invalid request body or unknown scorer type
        '422':
          description: LLM scorer could not be registered for this org
        '500':
          description: Trace-scoring step unavailable
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Org API key (scopes the request to its organization) or the shared
        trusted key (requires `X-Organization-Id` on every request).

````