> ## Documentation Index > Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 ````yaml /openapi.json get /v2/eval-runs 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: 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.