Async job pattern
All Pixii endpoints are asynchronous. Submit a job, get a job_id, then poll the Jobs API until the result is ready.
Listing Builder and Scale requests take approximately two minutes to complete. Rather than holding an open HTTP connection for two minutes — which times out in most environments — Pixii processes jobs asynchronously.
When you submit a request, you get a job_id back immediately. You then poll the Jobs API until the job is complete and your results are ready.
How it works
1. Submit a job → POST /v1/api/listing_builder → { job_id: "abc123", status: "pending" }
2. Poll for status → GET /v1/api/jobs/abc123 → { status: "processing" }
3. Poll again → GET /v1/api/jobs/abc123 → { status: "processing" }
4. Job complete → GET /v1/api/jobs/abc123 → { status: "completed", output: {...} }Job statuses
| Status | Meaning |
|---|---|
pending | Job received and queued |
processing | Job is actively running |
completed | Job finished successfully — output is ready |
failed | Job failed — see error field for details |
Polling for results
Call GET /v1/api/jobs/{job_id} repeatedly until the status is completed or failed. We recommend polling every 5 seconds.
If a job fails
When a job fails, the response includes an error code explaining what went wrong. Any credits consumed for a failed job are automatically refunded to your account.
Job expiry
Completed job results are available for retrieval for 7 days. After that the job record expires and the output URLs are no longer accessible. Download and store your images before then.
Webhooks
Webhook support is coming soon. When available, you’ll be able to register a URL that Pixii calls automatically when a job completes — eliminating the need to poll. Until then, polling the Jobs API is the recommended approach.