run prompts.md
Run Prompts
Queue saved prompts using the organization's configured targets.
Provide prompt_ids to run selected prompts, or omit them to run all active prompts. Saved prompt run settings apply to coding-agent targets. The response returns a run ID to poll with GET /v2/prompts/runs/{run_id}/status.
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/prompts/runs:
post:
tags:
- Prompts
summary: Run Prompts
description: >-
Queue saved prompts using the organization's configured targets.
Provide `prompt_ids` to run selected prompts, or omit them to run all
active prompts. Saved prompt run settings apply to coding-agent targets. The
response returns a run ID to poll with
`GET /v2/prompts/runs/{run_id}/status`.
operationId: v2_prompt_runs_create
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateV2PromptRunRequest'
examples:
selected_prompts:
summary: Run selected prompts
value:
prompt_ids:
- 550e8400-e29b-41d4-a716-446655440000
all_active_prompts:
summary: Run all active prompts
value:
force: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/V2PromptRunJobResponse'
'400':
description: No runnable configured targets were found for the selected prompts.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
required:
- detail
example:
detail: >-
No configured prompt targets were found for this organization.
Configure prompt targets first.
'402':
description: >-
The organization does not currently have enough credits for the
requested run.
content:
application/json:
schema:
type: object
properties:
detail:
type: object
properties:
error:
type: string
example: Insufficient credits
required:
type: number
description: Usage-based credits the requested run needs.
balance:
type: number
description: The organization's current credit balance.
required:
- error
- required
- balance
required:
- detail
'403':
description: >-
One or more configured targets are unavailable on the organization's
current plan.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
required:
- detail
example:
detail: 'Your current plan does not include: cursor'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'503':
description: The background queue is temporarily unavailable.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
required:
- detail
example:
detail: Background queue is not available
security:
- LightsageApiKeyAuth: []
components:
schemas:
CreateV2PromptRunRequest:
properties:
prompt_ids:
anyOf:
- items:
type: string
type: array
maxItems: 100
minItems: 1
- type: 'null'
title: Prompt Ids
description: >-
Prompt IDs from `GET /v2/prompts`. Omit this field to run all active
prompts.
force:
type: boolean
title: Force
description: >-
Run even when a prompt already ran today on the configured platform
and model.
default: false
additionalProperties: false
type: object
title: CreateV2PromptRunRequest
examples:
- prompt_ids:
- 550e8400-e29b-41d4-a716-446655440000
- force: true
V2PromptRunJobResponse:
properties:
id:
type: string
title: Id
description: Run ID to poll with `GET /v2/prompts/runs/{run_id}/status`.
job_id:
type: string
title: Job Id
description: Parent job ID. It currently matches `id`.
type:
type: string
const: prompts
title: Type
source_type:
type: string
const: prompts
title: Source Type
status:
anyOf:
- type: string
enum:
- pending
- running
- summarizing
- completed
- failed
- cancelled
- interrupted
- 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
description: >-
Current lifecycle stage, including `retrying` while interrupted
child jobs wait to be reclaimed.
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
description: >-
The estimated credit cost for prompt jobs or estimated USD cost for
API Performance jobs. Null when no estimate is available.
eval_count:
anyOf:
- type: integer
- type: 'null'
title: Eval Count
model_count:
anyOf:
- type: integer
- type: 'null'
title: Model Count
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
description: >-
Can be set while `status` is still `summarizing`; use `status` to
detect completion.
type: object
required:
- id
- job_id
- type
- source_type
- status
title: V2PromptRunJobResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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
securitySchemes:
LightsageApiKeyAuth:
type: apiKey
in: header
name: X-Lightsage-Api-Key