Async jobs

When a request is projected to run longer than ~8 seconds it returns a 202 with a jobId. Poll this endpoint until data.status is completed or failed. Status is one of pending | running | completed | failed.

While the job runs

// While running — HTTP 200, polling is free
{
  "data": { "jobId": "job_3kf…", "status": "running", "pollUrl": "/v1/jobs/job_3kf…", "estimatedSeconds": 12 },
  "meta": { "requestId": "req_jb…", "creditsCharged": 0, "platforms": ["vrbo"] }
}

On completion

The completed payload arrives in data.result in the same unified schema the synchronous endpoint would return, and meta.creditsCharged reports the credits for the work — charged exactly once, here.

// On success — HTTP 200; credits for the work are charged HERE, once
{
  "data": { "jobId": "job_3kf…", "status": "completed", "result": [ /* the endpoint's payload */ ] },
  "meta": {
    "requestId": "req_jb2…", "platforms": ["vrbo"], "creditsCharged": 4, "currency": "USD",
    "platformResults": [ { "platform": "vrbo", "status": "ok", "creditsCharged": 4, "cached": false, "count": 15 } ],
    "warnings": []
  }
}

Code samples

curl -sS "https://api.scoutingapi.com/v1/jobs/job_3kf…" \
  -H "Authorization: Bearer $SCOUTINGAPI_KEY"

Rules to know

• Polling is always 0 credits. The work is billed once, on success — never on the 202 and never on a poll.
• Results are retained 24 hours (jobs.expires_at); after that the id returns 404 job_not_found.
• Ownership is enforced. A jobId that belongs to another user returns the same 404 as a non-existent one — the id is not a capability.
• A failed job returns status: "failed" with creditsCharged: 0 — bad data is free, even asynchronously.