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

# List scores

> Returns a paginated list of scores for the authenticated application. Supports filtering by resource, name, source, and date range.



## OpenAPI

````yaml /openapi.yaml get /v1/scores
openapi: 3.0.3
info:
  contact:
    email: hello@agentmark.co
    url: https://docs.agentmark.co
  description: >-
    The AgentMark Gateway API lets you ingest traces, create scores, and
    retrieve prompt templates programmatically.


    Most developers should use the [AgentMark SDK](/introduction/overview) for
    integration.

    The REST API is for cases where you need direct HTTP access or are building
    a custom integration.


    Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship
    under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation
    window — see [API versioning & stability](/api-reference/versioning) for the
    full policy on what constitutes a breaking vs. additive change.
  title: AgentMark Gateway API
  version: '1.0'
servers:
  - description: Production (AgentMark Cloud)
    url: https://api.agentmark.co
  - description: Local dev server (`npx @agentmark-ai/cli dev`)
    url: http://localhost:9418
security:
  - AppId: []
    BearerAuth: []
tags:
  - description: Ingest, query, and export OpenTelemetry trace data.
    name: Traces
  - description: >-
      Coding-agent session ingest (outerlayer sync) and content-addressed
      session images.
    name: Agents
  - description: >-
      Eval trial-result ingest: per-trial score rows plus full-fidelity artifact
      blobs.
    name: Evals
  - description: Query individual spans across traces.
    name: Spans
  - description: Create, retrieve, list, and delete score records for spans and traces.
    name: Scoring
  - description: Structured-filter search across observability resources.
    name: Search
  - description: Query server feature availability.
    name: Capabilities
  - description: Per-model LLM pricing data. Public, unauthenticated.
    name: Pricing
  - description: >-
      Create, list, and revoke tenant API keys. Plaintext returned exactly once
      at creation.
    name: API Keys
  - description: >-
      List and retrieve score configuration definitions from the synced project
      config.
    name: Score Configs
  - description: Per-app named environments (e.g. `dev`, `prod`). CRUD for env lifecycle.
    name: Environments
  - description: >-
      App CRUD — the top-level tenant entity every other resource hangs off.
      Lets a headless agent provision an app without the dashboard.
    name: Apps
  - description: >-
      Cloud workers — terminal coding agents on managed compute. Launch one-shot
      runs or persistent multi-turn sessions against the app's connected repo;
      every response carries the dashboard deep link to the live thread.
    name: Workers
  - description: Service health checks.
    name: Health
paths:
  /v1/scores:
    get:
      tags:
        - Scoring
      summary: List scores
      description: >-
        Returns a paginated list of scores for the authenticated application.
        Supports filtering by resource, name, source, and date range.
      operationId: list-scores
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            default: 50
            maximum: 1000
            minimum: 1
            type: integer
        - in: query
          name: offset
          required: false
          schema:
            default: 0
            minimum: 0
            nullable: true
            type: integer
        - in: query
          name: start_date
          required: false
          schema:
            format: date
            type: string
        - in: query
          name: end_date
          required: false
          schema:
            format: date
            type: string
        - in: query
          name: resource_id
          required: false
          schema:
            type: string
        - in: query
          name: resource_type
          required: false
          schema:
            enum:
              - trace
              - span
            type: string
        - in: query
          name: name
          required: false
          schema:
            type: string
        - in: query
          name: source
          required: false
          schema:
            enum:
              - experiment
              - annotation
              - api
            type: string
        - in: query
          name: session_id
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        id:
                          format: uuid
                          type: string
                        label:
                          type: string
                        name:
                          type: string
                        reason:
                          type: string
                        resource_id:
                          type: string
                        score:
                          type: number
                        source:
                          type: string
                        user_id:
                          type: string
                      required:
                        - id
                        - resource_id
                        - name
                        - score
                        - label
                        - reason
                        - source
                        - created_at
                      type: object
                    type: array
                  pagination:
                    properties:
                      limit:
                        minimum: 0
                        type: integer
                      offset:
                        minimum: 0
                        type: integer
                      total:
                        minimum: 0
                        type: integer
                    required:
                      - total
                      - limit
                      - offset
                    type: object
                required:
                  - data
                  - pagination
                type: object
          description: A paginated list of scores.
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Invalid request parameters (validation failed).
        '401':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Missing or invalid API key.
components:
  securitySchemes:
    AppId:
      description: >-
        Application ID for tenant scoping. X-Outerlayer-App-Id is accepted as an
        equivalent header.
      in: header
      name: X-Agentmark-App-Id
      type: apiKey
    BearerAuth:
      description: API key (sk_agentmark_*)
      scheme: bearer
      type: http

````