SLIDESHOT [docs] Markdown
For agents: read the markdown version of these docs →

Runs

A run is a single recording session. Slideshot drives a real browser through the target_url to satisfy your goal, records the workflow, and renders a polished demo video. Runs are created by an agent or by the CLI on your behalf and move through a small set of lifecycle states.

Lifecycle

A run’s status is one of:

  • queued: The run was accepted and is waiting to be picked up.
  • running: The run is actively executing the workflow.
  • awaiting_input: The run paused mid-execution to ask for input (typically an OTP). It will resume once you submit a value, or fail when the input window expires.
  • succeeded: Terminal. Artifacts are ready to download.
  • failed: Terminal. The run could not complete the goal.
  • cancelled: Terminal. The run was cancelled by you or by your agent.

While a run is active, it also surfaces a progress_stage you can show in a UI:

  • null
  • normalizing_goal
  • executing
  • rendering_demo_video
  • rendering_intro
  • rendering_gif

progress_stage is for display only. It never changes lifecycle semantics.

Endpoints

  • POST /v1/agent/runs: Create a recording run.
  • GET /v1/agent/runs/:id: Read status, progress_stage, and the current awaiting_input prompt if any.
  • POST /v1/agent/runs/:id/input: Submit requested input such as an OTP.
  • POST /v1/agent/runs/:id/cancel: Cancel a queued or running run.
  • GET /v1/agent/runs/:id/artifacts: List output files. See Artifacts.

Create a run

The minimum payload is target_url and goal:

curl -X POST https://api.slideshot.ai/v1/agent/runs \
  -H "x-api-key: $SLIDESHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://app.example.com",
    "goal": "Create a new project and open the analytics dashboard.",
    "options": {
      "artifacts": { "gif": true }
    }
  }'
{ "run_id": "11111111-2222-3333-4444-555555555555" }

options is optional. Each sub-object is independent: you can pass only video, only auth, etc.

Run options

auth

Controls how Slideshot signs into the target app during the recording. See Credentials and Login to any web app.

  • { "source": "none" }: Do not log in.
  • { "source": "default" }: Use the default credential for the target domain.
  • { "source": "saved", "id": "<credential_uuid>" }: Use a specific saved credential.

video

Visual controls applied at recording and render time. See Customize video.

  • blur_emails: true masks email-shaped strings during capture so they never appear in any artifact.
  • shortcuts: true overlays mac-style key chips on completed keyboard actions.
  • cursor: "small" | "default" | "large" | "none". Controls the synthetic cursor rendered in the polished demo only; raw.mp4 is unaffected.
  • size: Output dimensions and inner framing. See Video and content size.
  • background: Solid or gradient canvas to frame the captured content on. See Background.

artifacts

  • gif: true renders demo.gif from the final demo.mp4. Default false.

intro

Prepends a branded title card to demo.mp4. See Intro templates.

{
  "intro": {
    "template": "simple-line-by-line-slide",
    "content": { "text": "Analytics, now in 60 seconds" },
    "style": {
      "background": { "type": "gradient", "from": "#0B1220", "to": "#101A33", "direction": "diagonal" },
      "textColor": "#FFFFFF"
    }
  }
}

The intro stage is best-effort: if it fails, the run still ships demo.mp4 without the card.

Poll for status

curl https://api.slideshot.ai/v1/agent/runs/$RUN_ID \
  -H "x-api-key: $SLIDESHOT_API_KEY"

Sample response while running:

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": "running",
  "progress_stage": "executing",
  "awaiting_input": null,
  "target_url": "https://app.example.com",
  "goal": "Create a new project and open the analytics dashboard.",
  "created_at": "2026-05-11T12:00:00Z",
  "updated_at": "2026-05-11T12:01:14Z"
}

Poll at most every two seconds. From the CLI, slideshot runs wait <RUN_ID> handles polling for you.

Handling awaiting input

When the recording browser reaches an OTP or magic-link step, the run pauses with status="awaiting_input" and the response includes an awaiting_input object:

{
  "status": "awaiting_input",
  "awaiting_input": {
    "prompt": "Enter the 6-digit code from your email",
    "requested_at": "2026-05-11T12:02:00Z",
    "expires_at": "2026-05-11T12:07:00Z"
  }
}

Submit the value before expires_at:

curl -X POST https://api.slideshot.ai/v1/agent/runs/$RUN_ID/input \
  -H "x-api-key: $SLIDESHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "123456" }'

The endpoint returns 204 and the run resumes from where it paused. Submitting input to a run that is not in awaiting_input returns 409.

The wait window itself is cut out of the final demo.mp4 so viewers do not see it.

Cancel a run

curl -X POST https://api.slideshot.ai/v1/agent/runs/$RUN_ID/cancel \
  -H "x-api-key: $SLIDESHOT_API_KEY"

Returns 204 on success. Returns 409 if the run has already reached a terminal state, and 404 if the run was not created by your API key.

The runner cancels cooperatively at checkpoint boundaries. Active recordings stop at the next safe point, terminate, and surface as cancelled.

After the run succeeds

Once status="succeeded", list artifacts:

curl https://api.slideshot.ai/v1/agent/runs/$RUN_ID/artifacts \
  -H "x-api-key: $SLIDESHOT_API_KEY"

See Artifacts for the shape of the response and what each artifact contains.

CLI shortcuts

The CLI maps each endpoint to a command. Use these when scripting:

slideshot runs create https://app.example.com \
  --goal "Open the analytics dashboard" \
  --options '{"artifacts":{"gif":true}}'

slideshot runs wait <RUN_ID>
slideshot runs artifacts <RUN_ID>
slideshot runs download <RUN_ID> --artifact demo.mp4 --dir ./artifacts
slideshot runs cancel <RUN_ID>
  • Credentials: save target-app credentials so runs can log in.
  • Artifacts: list and download outputs after a run succeeds.
  • Feedback: send feedback tied to specific runs.