> Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

---
title: Jobs and logs
"og:image": "https://libretto.sh/docs/og/libretto-cloud-api/jobs-and-logs.png"
---

> 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](/libretto-cloud-hosting/stealth#residential-proxy-locations) for the supported fields and combination rules.

Callback delivery order:

1. If the job has `callback_url` and `callback_secret`, Libretto Cloud delivers only to that per-job callback.
2. Otherwise, Libretto Cloud delivers to every active stored webhook endpoint for the tenant.
3. 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](/libretto-cloud-api/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](/libretto-cloud-api/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

```bash
curl -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"
    }
  }'
```

<CardGroup cols={3}>
  <Card title="Credentials" icon="lock" href="/libretto-cloud-api/credentials">
    Store credentials used by Libretto Cloud workflows.
  </Card>

  <Card title="Deployments and Workflows" icon="rocket" href="/libretto-cloud-api/deployments-and-workflows">
    Deploy workflows and inspect build state.
  </Card>

  <Card title="Webhooks" icon="lucide:webhook" href="/libretto-cloud-api/webhooks">
    Configure tenant-level job result webhooks.
  </Card>

  <Card title="Libretto Cloud API overview" icon="book-open" href="/libretto-cloud-api/overview">
    See the shared request format.
  </Card>
</CardGroup>