/v1/workspaces/{workspace_id}/jobsAuthCreate (enqueue) a trawl job
Queues an extraction: an agent browses from `suggested_urls` (or searches when there are none) and returns JSON matching `json_schema`. The job starts `queued`; poll `GET /jobs/{id}` until `status` is `succeeded`, `failed` or `cancelled`, or subscribe a webhook endpoint to `job.succeeded` / `job.failed`. Each agent step uses one credit; a workspace at zero credits gets 402. Send an `Idempotency-Key` so a retried request never queues a second job.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringPass a key (1..256 chars, [A-Za-z0-9._:-]) to make retries safe — replays return the original response for 24h.
Request body
json_schema*objectJSON Schema describing the shape of the extraction result. Must be a non-empty object with `type: "object"`.
Example: {"type":"object","properties":{"title":{"type":"string"}},"required":["title"]}
description*stringNatural-language description of what to extract.
Example: "Extract the product title and price from each page."
suggested_urlsarraySeed URLs the worker should start from.
Example: ["https://www.acme.com/pricing"]
webhook_idstring · uuidA webhook endpoint of this workspace to notify when the job finishes. Endpoints made before 17 Oct 2026 receive only the jobs that name them here; endpoints made under `/webhooks/endpoints` receive every job event they subscribe to, so leave this out for them.
Example: "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"
max_stepsnumberMaximum number of agent steps (one LLM call each) before the job stops. Defaults to 20. Multi-source extractions typically need 40+. The server additionally clamps this to an operator ceiling, so a very large value does not guarantee a very long run — `timeout_s` still applies.
Example: 40
timeout_snumberWall-clock timeout for the job, in seconds.
Example: 600
model_tierstringModel tier the worker should use (e.g. `standard`, `pro`).
Example: "standard"
Response · 201 Job created and queued.
id*string · uuidThe job's id.
workspace_id*string · uuidThe 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*objectThe JSON Schema the job was created with.
description*stringNatural-language description of what to extract.
suggested_urls*arraySeed URLs the worker starts from; null when none were given.
max_steps*integerMaximum number of agent steps (one LLM call each) before the job stops.
timeout_s*integerWall-clock timeout for the job, in seconds.
model_tier*stringModel tier the worker uses (e.g. `standard`, `pro`).
webhook_id*string · uuidThe webhook endpoint named at creation to notify when the job ends; null when none.
result*objectThe extracted data, shaped by `json_schema`. Null until the job succeeds.
error*stringWhy the job failed; null unless `status` is `failed`.
attempts*integerHow many times a worker has picked the job up.
enqueued_at*string · date-timeWhen the job was queued.
started_at*string · date-timeWhen a worker started it; null while queued.
completed_at*string · date-timeWhen it ended; null until then.
created_at*string · date-timeWhen the job was created.
Example
Request
POST https://api.trawl.productcraft.co/v1/workspaces/{workspace_id}/jobs
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"json_schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
}
},
"required": [
"title"
]
},
"description": "Extract the product title and price from each page.",
"suggested_urls": [
"https://www.acme.com/pricing"
],
"webhook_id": "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
"max_steps": 40,
"timeout_s": 600,
"model_tier": "standard"
}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"
}