POST/jobs

Durable jobs

Run bulk enrichment, live searches, or any work that may outlive an HTTP connection as a durable job. Stormy persists status, renews worker leases, retries transient provider failures with backoff, and prevents duplicate submission and double billing.

Request body

operationstringrequired

search_people, lookup_profile, or find_emails.

argumentsobjectrequired

The same arguments accepted by the corresponding synchronous endpoint.

delay_secondsinteger · default 0

Schedule up to seven days in the future.

priorityinteger · default 0

Range −10 to 10. Higher values are claimed first.

max_attemptsinteger · default 5

Range 1–10. Retries use exponential backoff.

Example request

curl -X POST 'https://stormy.ai/api/v1/jobs' \
  -H 'Authorization: Bearer YOUR_STORMY_API_KEY' \
  -H 'Idempotency-Key: creator-enrichment-batch-42' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation": "find_emails",
    "arguments": {
      "platform": "instagram",
      "targets": ["@creator_one", "@creator_two"]
    },
    "max_attempts": 5
  }'

Response

200 OK · application/json

{
  "ok": true,
  "job": {
    "id": "5582fc8d-54ee-450a-9386-450010e92c4b",
    "status": "retrying",
    "attempt": 2,
    "max_attempts": 5,
    "progress_current": 8,
    "progress_total": 25,
    "poll_after_seconds": 31,
    "terminal": false,
    "next_action": "poll_after_delay",
    "can_cancel": true
  }
}

Related endpoints

GET

/jobs/{job_id}

Read status and the event timeline. Poll using poll_after_seconds — it reflects the real provider cooldown.

GET

/jobs?status=running&limit=20

List recent jobs, optionally filtered by status.

DELETE

/jobs/{job_id}

Cancel queued, scheduled, throttled, or retrying work.

Every response includes a usage receipt: operation · metered_results · billed_results · cost_usd · credits · remaining_usage_usd. Reusing an Idempotency-Key returns the existing receipt instead of charging twice.