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.

Get the workflow output

POST /v1/jobs/create starts a run and returns a job_id. It does not return the data the workflow collected.

Whatever the handler returns is stored on the completed job as result. That object matches the workflow output schema.

Poll POST /v1/jobs/get until the job finishes, then read result. A job.completed webhook delivers the same field. See Webhooks.

12345678curl -X POST "https://api.libretto.sh/v1/jobs/get" \
  -H "x-api-key: $LIBRETTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "id": "<job-id>"
    }
  }'

12345678{
  "job_id": "<job-id>",
  "workflow": "scrape-page",
  "status": "completed",
  "result": {
    "title": "Example Domain"
  }
}

Jobs

The CLI jobs namespace is reserved for workflows deployed by your tenant:

123libretto cloud jobs create check-eligibility --params '{"member_id":"123"}'
libretto cloud jobs status <job-id>
libretto cloud jobs status <job-id> --watch

Use libretto cloud catalogue instead when discovering or running a workflow publicly shared by another tenant.

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
disable_default_proxy: optional boolean; Kernel only. Disables Kernel's default residential stealth proxy so traffic uses direct egress. Mutually exclusive with residential_proxy. Use when sites fail with ERR_TUNNEL_CONNECTION_FAILED on the default proxy.

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.

Use disable_default_proxy when the default managed proxy cannot reach the target (for example ERR_TUNNEL_CONNECTION_FAILED). It cannot be combined with residential_proxy.

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

This response does not include result. See Get the workflow output.

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: the workflow handler return value after the job completes. Matches schemas.output.
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"
    }
  }'