GET /v1/runs/:id — Retrieve Run Details

The GET /v1/runs/:id endpoint returns the complete stored record for a run that belongs to the authenticated user. The record is available immediately after POST /v1/run responds — the initial status will be "running" until the background job finishes. Once the run terminates, the same endpoint returns the final "pass" or "fail" status along with all step outcomes and, for AI-assisted runs, the full sequence of assist events.

Authentication

Pass an API key via the X-Api-Key header or a JWT via the Authorization: Bearer <token> header.

Path Parameters

string (UUID)

required

The run ID returned by POST /v1/run.

Response — 200 OK

The response body is a RunRecord object.

string (UUID)

Unique identifier for the run.

status

"pass" | "fail" | "running"

Current lifecycle status of the run.

startedAt

string (ISO 8601)

Timestamp when the run was registered and the browser session began.

durationMs

number

Total elapsed time in milliseconds. Will be 0 while the run is still in "running" status.

baseUrl

string

The root URL the run was executed against.

project

string

Project slug the run is associated with. Present when the run was created with a project value.

contextId

string

Optional external reference (e.g. Git commit SHA or CI build ID) supplied at run creation.

assisted

AssistedMeta object

Present for AI-assisted runs. Contains the metadata recorded at plan time.

Show AssistedMeta fields

assisted.goal

string

Natural-language goal the AI planner was given.

assisted.model

string

LLM model identifier used at plan time.

assisted.generatedAt

string (ISO 8601)

Timestamp when the plan was generated.

assisted.promptVersion

string

Internal version of the planning prompt template.

assisted.assistConfig

object

Optional v2 configuration recorded for this run (victory conditions, horizon limits, memory mode, etc.).

steps

StepOutcome[]

Ordered array of per-step execution results.

Show StepOutcome fields

steps[].index

number

Zero-based position of the step in the original plan.

steps[].action

string

The action type that was executed (e.g. "click", "fill", "goto").

steps[].ok

boolean

true if the step completed without error.

steps[].error

string

Human-readable error message. Present only when ok is false.

steps[].screenshotPath

string

Relative path to the PNG screenshot captured after this step. Present only when captureScreenshotAfterEachStep was enabled.

Serialised accessibility-tree snapshot captured after this step. Present only when captureA11yAfterEachStep was enabled.

videoPath

string

Relative path to the recorded WebM video file. Present only when recordVideoOnFailure was enabled and the run ended in "fail" status.

events

AssistEvent[]

Chronologically ordered array of assist pipeline events. Present only for AI-assisted runs. Empty for manual (non-assisted) runs.

Show AssistEvent fields

events[].seq

number

Monotonically increasing sequence number within the run.

events[].type

AssistEventType

One of: recon, plan_chunk, loop_state, horizon_start, horizon_end, victory_check, memory_hit, memory_miss, step_start, step_success, step_failure, heal_start, heal_action, heal_success, heal_failure, run_end.

events[].at

string (ISO 8601)

Timestamp when the event was emitted.

events[].stepIndex

number

Zero-based index of the step this event is associated with, if applicable.

events[].payload

object

Event-specific data. Shape varies by type.

Error Responses

Status	Body
`404`	`{ ok: false, error: "not found" }` — run does not exist or belongs to a different user

Examples

curl https://api.ghostly.dev/v1/runs/d1e2f3a4-0000-4000-8000-112233445566 \
  -H "X-Api-Key: gly_YOUR_API_KEY"

If the run is still in "running" status, durationMs will be 0 and steps may be empty or partial depending on how many steps have completed. Poll this endpoint or use the SSE stream for live updates.

Overview

Authentication

Runs

Projects

Settings

GET /v1/runs/:id — Retrieve Run Details

Authentication

Path Parameters

Response — 200 OK

Error Responses

Examples

Build docs developers (and LLMs) love

Overview

Authentication

Runs

Projects

Settings

Documentation Index

​Authentication

​Path Parameters

​Response — 200 OK

​Error Responses

​Examples

Build docs developers (and LLMs) love

Authentication

Path Parameters

Response — 200 OK

Error Responses

Examples