Submit a scrape job

POST

/api/v1/jobs

curl -X POST 'https://dashboard.justcrawl.io/api/v1/jobs' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"urlItemId":"550e8400-e29b-41d4-a716-446655440000"}'

• Production

Queue a job for an existing URL item against a workflow. If workflowId is omitted the gateway resolves the workflow via the URL’s domain route. Returns 201 immediately with the new jobId and status: pending; poll GET /api/v1/jobs/{jobId} (or use the batch endpoint) for completion. Quota gate applies: 402 Insufficient credits when the org’s quota is exhausted, with remainingCredits echoed back in the body.

Authorizations

• bearerAuth

Request Body ^required

Media type application/json

object

urlItemId

required

ID of the URL item to scrape. Create one via POST /api/v1/urls.

string format: uuid

workflowId

Optional. When omitted, resolves from the URL’s domain route.

string format: uuid

Examples

Example default

Submit a URL-item job

{
  "urlItemId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Responses

201

Job created successfully

Media type application/json

object

jobId

required

string format: uuid

status

required

Always pending on creation. Poll GET /api/v1/jobs/{jobId} for the real-time status.

string

Allowed values: pending

url

required

string

resolvedWorkflow

Present only when workflowId was omitted and the gateway resolved it via the URL’s domain route.

object

Examples

Example default

Job accepted

{
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "url": "https://www.walmart.com/ip/12345"
}

400

Validation failed — request body or query is missing/invalid

Media type application/json

object

error

string

Example

{
  "error": "Missing or invalid \"url\" field"
}

401

Missing or invalid authentication token

Media type application/json

object

error

string

Example

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

402

Insufficient credits

Media type application/json

object

error

required

string

Allowed values: QUOTA_EXCEEDED

message

required

string

plan

string

nullable

remainingCredits

integer

nullable

isTrialExpired

boolean

nullable

Example

{
  "error": "QUOTA_EXCEEDED",
  "message": "Credits exhausted. Recharge to continue.",
  "plan": "free",
  "remainingCredits": 0,
  "isTrialExpired": false
}

403

Insufficient permissions for this operation

Media type application/json

object

error

string

Example

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

404

Resource not found

Media type application/json

object

error

string

Example

{
  "error": "Workflow not found"
}

500

Unexpected server error. Logs and PostHog $exception capture

Media type application/json

object

error

string

Example

{
  "error": "Something went wrong"
}