Trawl API reference

Trawl API · Jobs

get/v1/workspaces/{workspace_id}/jobs/{id}Auth

Get a single trawl job

The job with its current `status`, and `result` (JSON matching the job's `json_schema`) once it has `succeeded` or `error` once it has `failed`. Poll this until `status` is terminal; every read is free.

Path parameters

workspace_id*string · uuid

Id of the workspace.

id*string · uuid

Id of the job.

Response · 200 Job row.

id*string · uuid

The job's id.

workspace_id*string · uuid

The workspace that owns the job.

status*object

`queued` until a worker picks it up, then `running`; it ends `succeeded` (the result is in `result`), `failed` (see `error`) or `cancelled`.

json_schema*object

The JSON Schema the job was created with.

description*string

Natural-language description of what to extract.

suggested_urls*array

Seed URLs the worker starts from; null when none were given.

max_steps*integer

Maximum number of agent steps (one LLM call each) before the job stops.

timeout_s*integer

Wall-clock timeout for the job, in seconds.

model_tier*string

Model tier the worker uses (e.g. `standard`, `pro`).

webhook_id*string · uuid

The webhook endpoint named at creation to notify when the job ends; null when none.

result*object

The extracted data, shaped by `json_schema`. Null until the job succeeds.

error*string

Why the job failed; null unless `status` is `failed`.

attempts*integer

How many times a worker has picked the job up.

enqueued_at*string · date-time

When the job was queued.

started_at*string · date-time

When a worker started it; null while queued.

completed_at*string · date-time

When it ended; null until then.

created_at*string · date-time

When the job was created.

Example

Request

GET https://api.trawl.productcraft.co/v1/workspaces/{workspace_id}/jobs/{id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "status": {},
  "json_schema": {},
  "description": "string",
  "suggested_urls": [
    "string"
  ],
  "max_steps": 0,
  "timeout_s": 0,
  "model_tier": "string",
  "webhook_id": "00000000-0000-0000-0000-000000000000",
  "result": {},
  "error": "string",
  "attempts": 0,
  "enqueued_at": "2026-01-01T00:00:00.000Z",
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}