Start benchmark

POST

/api/v1/benchmarks

curl --request POST \
  --url https://dashboard.justcrawl.io/api/v1/benchmarks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "urls": [ "https://example.com" ] }'

• Production

Kicks off a benchmark run — every connected provider scrapes the supplied URLs in parallel so the platform can rank them on success rate, latency, and cost. Returns 201 with a pending benchmark record immediately; the actual scraping happens async (setImmediate → runBenchmark). Poll GET /benchmarks/{id} for status.

• Hard cap: 20 URLs per benchmark. Larger sets return 400.
• Auto-detect: providers are taken from this org’s connected accounts; orgs with zero connected providers get 400 with an actionable message.
• One-at-a-time per org: a second POST while one is pending or running returns 409. Invalid URLs are silently skipped; if every URL is invalid the call 400s.

Authorizations

• bearerAuth

Request Body ^required

Media type application/json

object

urls

required

Array<string>

<= 20 items

Example ^generated

{
  "urls": [
    "https://example.com"
  ]
}

Responses

201

Benchmark queued; scraping runs async.

Media type application/json

object

id

string format: uuid

status

string

Allowed values: pending running completed failed

urls

Array<string>

providerIds

Array<string>

totalProbes

integer

completedProbes

integer

failedProbes

integer

skippedProviders

Array<string>

error

string

nullable

createdAt

string format: date-time

Example

{
  "status": "pending"
}

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

403

Insufficient permissions for this operation

Media type application/json

object

error

string

Example

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

409

Operation conflicts with current resource state

Media type application/json

object

error

string

Example

{
  "error": "Resource already exists"
}

500

Unexpected server error. Logs and PostHog $exception capture

Media type application/json

object

error

string

Example

{
  "error": "Something went wrong"
}