⚡ Async Bulk Processing

Process up to 500,000 URLs per job. Perfect for data enrichment pipelines, SEO audits, and large-scale metadata extraction.

Endpoints

POST/v1/jobsCreate a new job

GET/v1/jobsList all jobs

GET/v1/jobs/:idGet job status

DELETE/v1/jobs/:idCancel a job

GET/v1/jobs/:id/resultsGet job results

Create Job - Request Body

Name	Type	Default	Description
`type`	`enum`	-	extract \| validate \| analyze
`urls`	`array`	-	Array of URLs (1 to 50,000 per request)
`options.include_screenshot`	`boolean`	`false`	Include screenshots
`options.include_quality_score`	`boolean`	`true`	Include quality scores
`options.cache`	`boolean`	`true`	Use cached results
`callback.url`	`string`	-	Webhook URL for completion notification
`callback.format`	`enum`	`json`	json \| csv \| ndjson
`priority`	`enum`	`normal`	low \| normal \| high

Create Job Example

curl -X POST "https://api.katsau.com/v1/jobs" \
  -H "Authorization: Bearer ks_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "extract",
    "urls": [
      "https://example1.com",
      "https://example2.com",
      "https://example3.com"
    ],
    "options": {
      "include_quality_score": true
    },
    "callback": {
      "url": "https://myapp.com/webhooks/job-complete",
      "format": "json"
    },
    "priority": "normal"
  }'

Create Response

{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "type": "extract",
    "status": "queued",
    "total_urls": 3,
    "estimated_time_seconds": 1,
    "priority": "normal",
    "expires_at": "2024-01-22T00:00:00Z",
    "created_at": "2024-01-15T12:00:00Z"
  },
  "meta": { "request_id": "req_abc123" }
}

Job Status Response

{
  "success": true,
  "data": {
    "job_id": "job_abc123xyz",
    "type": "extract",
    "status": "processing",
    "progress": {
      "total": 1000,
      "completed": 456,
      "failed": 12,
      "percentage": 47
    },
    "priority": "normal",
    "results_url": null,
    "started_at": "2024-01-15T12:00:05Z",
    "estimated_completion": "2024-01-15T12:01:30Z",
    "expires_at": "2024-01-22T00:00:00Z"
  }
}

Results Formats

Use the format query parameter on /v1/jobs/:id/results:

json

Standard JSON with pagination. Best for APIs.

csv

CSV file download. Best for spreadsheets.

ndjson

Newline-delimited JSON. Best for streaming.

Plan Limits

Plan	Max URLs/Job	Concurrent	Retention
Free	Not available	-	-
Starter	1,000	1 job	1 day
Pro	10,000	3 jobs	7 days
Business	50,000	10 jobs	30 days
Enterprise	500,000	50 jobs	90 days

Job Lifecycle

queued→processing→completed|failed|cancelled