List Runs

Returns custom eval runs, ordered newest first, with lifecycle state and progress. Includes scheduled, onboarding, and pull request runs and runs started in the Lightsage app, as well as runs started through POST /v2/eval-runs.

OpenAPI

openapi: 3.1.0
info:
  title: Lightsage Public API
  description: Public API for Lightsage CLI and external integrations.
  version: 1.0.0
servers:
  - url: https://api.lightsage.com
    description: Production
security: []
tags:
  - name: Status
    description: Check API availability and validate the calling API key.
  - name: Visibility
    description: >-
      Measure visibility, citations, competitors, and prompt performance across
      answer platforms.
  - name: Prompts
    description: Manage tracked prompts and topics, and inspect their stored runs.
  - name: Opportunities
    description: Review ranked opportunities computed from prompt visibility results.
  - name: Tasks
    description: Manage the persisted action queue and task lifecycle.
  - name: Site Audits
    description: Review website audit results and page-level findings.
  - name: Agent Analytics
    description: >-
      See which coding agents, AI bots, and people visit your tracked sites,
      which pages they read, which pages return errors, and where the visits
      come from.
  - name: Evals
    description: Define eval tasks, judges, subjects, and saved configurations.
  - name: Eval Templates
    description: >-
      Select reusable judges, targets, schedules, metadata, and runtime settings
      with `POST /v2/eval-templates`, then copy only those settings into
      prompt-specific evals with `POST /v2/evals/batch`. Templates never contain
      prompts and remain independent from evals created from them.
  - name: Eval Runs
    description: Start eval runs and inspect their lifecycle state.
  - name: Eval Results
    description: Review completed eval outcomes and diagnostic details.
  - name: Agent Preference
    description: >-
      Compare your company head-to-head with a tracked competitor. Create a
      comparison with `POST /v2/agent-preference/evals`, run it with `POST
      /v2/eval-runs`, then read which company agents recommended.
  - name: Agents
    description: List runnable coding-agent harness and model combinations.
  - name: Repositories
    description: Manage reusable Git repository workspaces.
  - name: Environments
    description: List reusable runtime environments without exposing secret values.
  - name: MCP Servers
    description: List reusable MCP server integrations without exposing credentials.
  - name: CLIs
    description: List reusable command-line interfaces without exposing setup commands.
  - name: Skills
    description: List reusable skills available to workflows and evals.
paths:
  /v2/eval-runs:
    get:
      tags:
        - Eval Runs
      summary: List Runs
      description: >-
        Returns custom eval runs, ordered newest first, with lifecycle state and
        progress. Includes scheduled, onboarding, and pull request runs and runs
        started in the Lightsage app, as well as runs started through `POST
        /v2/eval-runs`.
      operationId: v2_eval_runs_list
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 25
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2EvalRunsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - LightsageApiKeyAuth: []
components:
  schemas:
    V2EvalRunsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/V2EvalRun'
          type: array
          title: Data
        count:
          type: integer
          title: Count
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
        - count
        - limit
        - offset
      title: V2EvalRunsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    V2EvalRun:
      properties:
        id:
          type: string
          title: Id
          description: Run ID to use when polling eval-run status.
        job_id:
          type: string
          title: Job Id
          description: Alias of `id` for the durable parent job.
        eval_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Id
          description: Saved eval definition ID, including one created by a direct run.
        eval_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Name
          description: Display name captured for the eval when the run was created.
        configuration_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Configuration Id
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
          description: Perspective applied to every attempt in this simulation.
        agent:
          items:
            type: string
          type: array
          title: Agent
          description: Runnable agents selected for this simulation.
        prompt_count:
          type: integer
          minimum: 1
          title: Prompt Count
          description: Number of prompts included in the simulation.
          default: 1
        runs:
          type: integer
          minimum: 1
          title: Runs
          description: Independent attempts requested for every prompt-agent pair.
          default: 1
        attempt_count:
          type: integer
          minimum: 1
          title: Attempt Count
          description: Total concrete attempts after all fan-out dimensions.
          default: 1
        status:
          type: string
          title: Status
          description: >-
            Terminal values: `completed`, `failed`, and `cancelled`. Recoverable
            interruptions are reported as `running` with stage `retrying`.
        stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Stage
        dispatch_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Dispatch Id
        progress:
          $ref: '#/components/schemas/PublicEvalRunProgress'
        estimated_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimated Cost
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
      type: object
      required:
        - id
        - job_id
        - status
      title: V2EvalRun
    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
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PublicEvalRunProgress:
      properties:
        total:
          type: integer
          title: Total
          default: 0
        queued:
          type: integer
          title: Queued
          default: 0
        running:
          type: integer
          title: Running
          default: 0
        completed:
          type: integer
          title: Completed
          default: 0
        failed:
          type: integer
          title: Failed
          default: 0
        cancelled:
          type: integer
          title: Cancelled
          default: 0
        retrying:
          type: integer
          title: Retrying
          description: >-
            Recoverable child jobs waiting to be retried. These remain active
            and are excluded from `percent`.
          default: 0
        interrupted:
          type: integer
          title: Interrupted
          description: Deprecated compatibility alias for `retrying`; use `retrying`.
          default: 0
          deprecated: true
        percent:
          type: number
          title: Percent
          description: >-
            The percentage of child jobs in a final state (`completed`,
            `failed`, or `cancelled`). It can reach `100` while the parent job
            is still summarizing, so use `status` to detect completion.
          default: 0
      type: object
      title: PublicEvalRunProgress
  securitySchemes:
    LightsageApiKeyAuth:
      type: apiKey
      in: header
      name: X-Lightsage-Api-Key