Async Mode & Cancellation

Two related features: opting into the slow-but-fire-and-forget path, and pulling the plug on a running job.

Async Mode

/batch and /crawl accept async_mode: true in the request body.

	Sync (default)	async_mode: true
Latency	Seconds–minutes	Up to 24 hours
Cancellable	Yes	Yes
Failure behavior	Returns errors per URL	Falls back to sync transparently if it fails

async_mode does not reduce the number of credits you spend. You pay the same 1 credit per URL either way. The difference is purely latency: use it when you don't need results immediately and want to fire off a large batch without holding a connection open.

{
  "urls": ["https://example.com/1", "https://example.com/2"],
  "schema": [{ "field": "title", "type": "string", "example": "X" }],
  "async_mode": true
}

The response shape is identical to sync. Runo waits for the batch to finish before responding (long-poll with a generous client timeout).

Job IDs and Cancellation

Every response (/extract, /batch, /crawl) includes an X-Job-ID header:

X-Job-ID: job_a1b2c3d4e5f6

You can cancel a running job from any other connection by issuing:

DELETE /v1/jobs/{job_id}
X-API-Key: sk_live_...

Cancellation is owner-scoped (you can only cancel your own jobs) and cooperative. The job exits at the next safe checkpoint, so it may finish a URL or two after the request lands.

Refund Rules

Endpoint	What's refunded
/extract	Nothing. Extract is one unit. Returns JOB_CANCELLED.
/batch	Unstarted URLs are refunded. Completed URLs keep their results.
/crawl	All units that didn't run are refunded to the monthly counter. Pro/Scale overage credits restored to the prepaid balance.

In /batch and /crawl results, units that didn't run appear as:

{ "url": "...", "status": "error", "error": { "code": "JOB_CANCELLED", "retryable": false } }

The top-level crawl_meta (or cancelled flag on batch) reports cancelled: true.

List Running Jobs

curl https://api.scrapewithruno.com/v1/jobs \
  -H "X-API-Key: $RUNO_API_KEY"

Returns the jobs you currently own.

End-to-End Example

# 1. Start a crawl, capture the job_id from headers
curl -isS -X POST https://api.scrapewithruno.com/v1/crawl \
  -H "X-API-Key: $RUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seed_url": "https://example.com",
    "schema": [{ "field": "title", "type": "string", "example": "x" }],
    "crawl": { "follow_pattern": "https://example.com/*", "max_pages": 100 }
  }' | tee /tmp/crawl.out

# 2. Cancel it mid-flight from another shell
JOB=$(grep -i '^x-job-id:' /tmp/crawl.out | awk '{print $2}' | tr -d '\r')
curl -X DELETE "https://api.scrapewithruno.com/v1/jobs/$JOB" \
  -H "X-API-Key: $RUNO_API_KEY"

Error Codes

Code	When
JOB_CANCELLED	Per-URL marker for unstarted units in batch/crawl results
JOB_NOT_FOUND	DELETE on an unknown or already-completed job (404)
JOB_FORBIDDEN	DELETE on someone else's job (403)