Trawl API reference

Trawl API · Jobs

post/v1/workspaces/{workspace_id}/jobsAuth

Create (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 · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Pass a key (1..256 chars, [A-Za-z0-9._:-]) to make retries safe — replays return the original response for 24h.

Request body

json_schema*object

JSON 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*string

Natural-language description of what to extract.

Example: "Extract the product title and price from each page."

suggested_urlsarray

Seed URLs the worker should start from.

Example: ["https://www.acme.com/pricing"]

webhook_idstring · uuid

A 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_stepsnumber

Maximum 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_snumber

Wall-clock timeout for the job, in seconds.

Example: 600

model_tierstring

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

Example: "standard"

Response · 201 Job created and queued.

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

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"
}