Async jobs

202 + polling pattern for AI endpoints.

Updated 2026-05-24
4 min read

Some operations take 30–90 seconds — listing localization across multiple locales, App Store review simulation, screenshot localization. Rather than holding the HTTP connection open, the API returns 202 Accepted plus a job_id immediately and runs the work in the background.

The pattern

1

Kick off the work

bash
curl -s -X POST \
  https://forvibe.app/api/v1/projects/$PROJECT_ID/simulations/metadata \
  -H "Authorization: Bearer fvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'
json
// HTTP/1.1 202 Accepted
// Location: /api/v1/jobs/df41...
{
  "job_id": "df41...",
  "status": "pending",
  "type": "review_simulation",
  "poll_url": "/api/v1/jobs/df41..."
}
2

Poll the job endpoint

bash
curl -s https://forvibe.app/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer fvk_live_..."

Status progresses through these values:

  • pending — accepted, not yet started
  • in_progress / processing — running
  • completed — finished successfully, result populated
  • failed — error; error.message explains why
3

Read the result

json
{
  "job_id": "df41...",
  "type": "review_simulation",
  "status": "completed",
  "progress": null,
  "result": {
    "overall_summary": { ... },
    "metadata_review": { ... }
  },
  "error": null,
  "created_at": "2026-05-24T10:01:22Z",
  "updated_at": "2026-05-24T10:01:54Z"
}

Polling recommendations

  • First poll: 5 seconds after the 202.
  • Subsequent polls: every 3–5 seconds.
  • Give up after 2 minutes — if it's still pending past that, check the status returned and surface to your user.
  • Each poll counts as one request against the 120/min rate limit.

Resource-specific read endpoints

For review simulations specifically, GET /api/v1/simulations/:id returns the same row with richer fields (full codebase_review, combined_findings). Use the unified /jobs/:id endpoint when you don't know the job type in advance.

Async endpoint inventory

  • POST /projects/:id/listings/localize — AI translation (15 credits/locale).
  • POST /projects/:id/simulations/metadata — App Store review simulation (50 credits, paid plan).