Jobs and logs

Use the jobs API to run workflows and inspect results, and use the logs API to fetch executor logs for recent jobs.

All routes on this page require x-api-key.

Jobs

POST `/v1/jobs/create`

Start a workflow job.

Request fields:

workflow: deployed workflow name
params: workflow input object
nonce: optional idempotency-style nonce
timeout_seconds: optional timeout, default 1800, max 3600
headless: optional boolean browser mode override
start_url: optional start URL override for browser launch
gpu: optional boolean GPU override
viewport: optional { width, height } viewport override
callback_url: optional callback URL
callback_secret: optional callback secret
skip_callbacks: optional boolean
residential_proxy: optional residential proxy location object

If you set callback_url, you must also set callback_secret.

Prefer declaring startUrl, gpu, and viewport on the workflow definition so they travel with the deploy artifact. Use the job-level fields when you need a one-off override, or until the hosted executor applies workflow launch metadata automatically.

Use residential_proxy for location-sensitive runs that need traffic to originate from a specific residential proxy country, US state, city, ZIP code, or ASN. See Residential proxy locations for the supported fields and combination rules.

Callback delivery order:

If the job has callback_url and callback_secret, Libretto Cloud delivers only to that per-job callback.
Otherwise, Libretto Cloud delivers to every active stored webhook endpoint for the tenant.
If skip_callbacks is true, Libretto Cloud does not deliver callbacks or stored webhooks.

Use callback_url for one-off or environment-specific result delivery. Use stored webhook endpoints for long-lived production destinations. See Webhooks for payload fields and signature headers.

Response fields:

success
job_id
status: always running
message

POST `/v1/jobs/list`

List jobs for the current tenant.

Request fields:

status: optional status filter
limit: optional page size, default 20, max 100
cursor: optional pagination cursor from next_cursor

Response fields:

jobs
next_cursor

Each job summary includes:

job_id
deployment_id
workflow_id
workflow
status
created_at
completed_at

POST `/v1/jobs/get`

Return a single job and its result data.

Request fields:

id: job id

Response fields:

job_id
deployment_id
deployment_version
workflow_id
workflow
params
status
created_at
started_at
completed_at
result
error
mapped_stack

Use Recordings when you need the job's recording URL.

POST `/v1/jobs/debugReport`

Return the hosted debug or autofix report for a failed job.

Request fields:

id: job id

Response fields:

job_id
debug_agent_status
debug_agent_mode
error
tldr
handoff_prompt
screenshot_url
dom_snapshot_url
autofix_summary
autofix_deployment_id
email_sent_at
job_error
job_mapped_stack
job_params
job_workflow

POST `/v1/jobs/cancel`

Cancel a queued or running job.

Request fields:

id: job id

Response fields:

success
message

Logs

POST `/v1/logs/list`

Fetch recent executor logs for one job or for recent jobs in the tenant.

Request fields:

jobId: optional job id
workflow: optional workflow-name filter
level: optional info, warn, or error
pageToken: optional next-page token
limit: optional page size, default 100, max 1000

Response fields:

logs
nextPageToken

Each log entry includes:

jobId
workflow
level
message
timestamp

Example job run

1234567891011121314curl -X POST "https://api.libretto.sh/v1/jobs/create" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "workflow": "check-eligibility",
      "params": {
        "memberId": "12345"
      },
      "timeout_seconds": 300,
      "callback_url": "https://example.com/libretto/job-callback",
      "callback_secret": "replace-with-your-secret"
    }
  }'