List jobs

GET

/api/v1/jobs

curl -X GET 'https://api.justcrawl.io/api/v1/jobs?status=completed&pageSize=10' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY'

import os, requests
r = requests.get(
    'https://api.justcrawl.io/api/v1/jobs',
    headers={'Authorization': f'Bearer {os.environ["JUSTCRAWL_API_KEY"]}'},
    params={'status': 'completed', 'pageSize': 10},
)
r.raise_for_status()
print(r.json()['items'])

const params = new URLSearchParams({ status: 'completed', pageSize: '10' });
const res = await fetch(`https://api.justcrawl.io/api/v1/jobs?${params}`, {
  headers: { Authorization: `Bearer ${process.env.JUSTCRAWL_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { items } = await res.json();

Paginated list of scrape jobs in the current org. Filters compose: pass any combination of status, workflowId, scheduleId, domain, tag, plus the timestamp range filters (createdAfter/createdBefore/updatedAfter/updatedBefore). Heavy fields (executionTrace, nodeState) are stripped from list responses — fetch the single-job endpoint to get them. Each item carries cost derived from the org’s vendor-cost table, plus the credit line (creditsCharged, creditOutcome, creditNote) so a failed row says whether its charge came back.

Authorizations

bearerAuth

Parameters

Query Parameters

page

integer

Page number (default 1)

pageSize

integer

Items per page (default 25, max 100)

status

string

Allowed values: pending running completed failed waiting_retry extracting extraction_done

Filter by job status

workflowId

string format: uuid

Filter by workflow ID

Responses

200

Paginated list of jobs

application/json

object

items

Array<object>

object

string format: uuid

status

string

Allowed values: pending running completed failed waiting_retry extracting extraction_done

url

string

workflowId

string format: uuid

version

integer

providerId

string

nullable

statusCode

integer

nullable

latencyMs

integer

nullable

errorType

string

nullable

errorMessage

string

nullable

scheduleId

string format: uuid

nullable

purpose

Whether this is a customer crawl or an auxiliary Playground preview capture.

string

Allowed values: crawl preview_capture

parentJobId

Parent crawl ID for a preview capture. Null for ordinary crawl jobs.

string format: uuid

nullable

creditsCharged

Credits deducted for this job when it was submitted. 0 when the org is not charged per job (enterprise and platform-managed plans, backfills, extraction fan-out children and webhook-ingest jobs). null when the amount is not known — the job was recorded by a release that predates per-job charge stamping; such a job always reports creditOutcome: pending.

integer

nullable

creditOutcome

What happened to the charge. not_charged — this job never cost a credit. pending — charged, and the outcome is not decided yet. kept — charged, and the charge stands. refunded — charged, and the credit was returned because no provider delivered a page. A crawl that fails at every provider is free.

string

Allowed values: not_charged pending kept refunded

creditNote

One sentence saying why the charge was kept or returned, e.g. credit returned: no provider delivered a page. null while the outcome is not_charged or pending. Display it as-is — the wording is the API’s, not the client’s.

string

nullable

createdAt

string format: date-time

completedAt

string format: date-time

nullable

total

integer

Examples

default

Paginated job list

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "completed",
      "url": "https://www.walmart.com/ip/12345",
      "workflowId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
      "version": 3,
      "providerId": "brightdata",
      "statusCode": 200,
      "latencyMs": 1842,
      "cost": 0.00135,
      "purpose": "crawl",
      "parentJobId": null,
      "creditsCharged": 1,
      "creditOutcome": "kept",
      "creditNote": "credit kept: page delivered",
      "createdAt": "2026-06-06T15:30:00.000Z",
      "completedAt": "2026-06-06T15:30:02.000Z"
    }
  ],
  "total": 1
}

401

Missing or invalid authentication token

application/json

object

error

string

Example

{
  "error": "Missing or invalid authentication token"
}

403

Insufficient permissions for this operation

application/json

object

error

string

Example

{
  "error": "No organization. Complete onboarding first."
}

500

Unexpected server error. Logs and PostHog $exception capture

application/json

object

error

string

Example

{
  "error": "Something went wrong"
}