Jobs & retries

Submit and track a job

Submit to POST /v1/products/{product}/jobs. The 202 response returns a public dap_… job ID. Save it and read GET /v1/product-jobs/{job_id} for status and results. Use the same organization and team context for uploads, submission, and reads.

Poll for completion

Request parameters and response schema Set JOB_ID to the returned job ID, BEEBLE_API_KEY to your key, and BEEBLE_TEAM_ID if your organization uses internal teams:

curl --fail-with-body "https://api.beeble.ai/v1/product-jobs/$JOB_ID" \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}"

import os
import requests

headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
if team_id := os.environ.get("BEEBLE_TEAM_ID"):
    headers["X-Beeble-Team-Id"] = team_id

response = requests.get(
    f"https://api.beeble.ai/v1/product-jobs/{os.environ['JOB_ID']}",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())

const headers = { "x-api-key": process.env.BEEBLE_API_KEY }
if (process.env.BEEBLE_TEAM_ID)
  headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
const response = await fetch(
  `https://api.beeble.ai/v1/product-jobs/${process.env.JOB_ID}`,
  { headers, signal: AbortSignal.timeout(30_000) },
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())

Response (200, abbreviated):

{
  "id": "dap_example",
  "status": "processing",
  "outputs": {}
}

Status	Action
`success`	Download the files in `outputs`.
`failed`, `cancelled`, `credit_required`	Stop polling and inspect the error or credit issue.
Other statuses	Wait before polling again.

Set a polling timeout and save the job ID to resume later. A client timeout does not cancel the job. You can also use webhooks.

Download results

Read outputs after success. For SwitchX, download outputs.render; other products use different fields. Each product guide includes a completed response and the field to download. Check that a URL is non-null before downloading. If a signed URL expires, read the same job again for a fresh URL.

Output schemas

Use the response schema for the endpoint you called. The model catalog’s input_schema describes submission inputs, not the returned files. The OpenAPI response schema defines the job envelope. outputs is an open object; product-specific download fields are not typed in that schema. For SwitchX with alpha_mode: "fill", outputs.alpha is null.

Safe retries

Save the idempotency key and request body before submitting.
On a timeout or lost response, retry with the same key, body, organization, and team.
Use a new idempotency key for each new job. Before replacing an earlier attempt, confirm it was rejected or failed.

submitting or unknown may mean the job has already started and charged. Replay the original request; do not submit a replacement with a new key.

Changing the body under the same key returns 409. See Billing & credits before assuming a failed job was refunded.

Uncertain submissions

Organization API keys have no concurrent-job limit. An uncertain submission still retains its original request identity: waiting does not resolve its outcome or make a replacement safe. Replay the same request, and contact support if its outcome cannot be confirmed.

List jobs

curl --fail-with-body "https://api.beeble.ai/v1/product-jobs?limit=20" \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}"

import json
import os
import requests

headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
if team_id := os.environ.get("BEEBLE_TEAM_ID"):
    headers["X-Beeble-Team-Id"] = team_id

response = requests.get(
    "https://api.beeble.ai/v1/product-jobs?limit=20",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

const headers = { "x-api-key": process.env.BEEBLE_API_KEY }
if (process.env.BEEBLE_TEAM_ID) {
  headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
}
const response = await fetch("https://api.beeble.ai/v1/product-jobs?limit=20", {
  headers,
  signal: AbortSignal.timeout(30_000),
})
if (!response.ok) throw new Error(await response.text())
console.log(JSON.stringify(await response.json(), null, 2))

Request parameters and response schema Response (200, empty page):

{
  "jobs": [],
  "next_cursor": null
}

The response contains jobs and next_cursor. Pass a non-null next_cursor as before to read the next page. limit accepts 1–100 and defaults to 20. Listings contain saved statuses; read an individual job for fresh status and output URLs.

Access after submission

Reads are scoped to the key owner, organization, and selected team. Disabling a product for new submissions still allows reads and replay of its existing jobs, subject to continuing key, membership, and organization security checks. Revoking a key or removing its access can also stop callback delivery.

Get started

Products

Core concepts

Integrations

Submit and track a job

Poll for completion

Download results

Output schemas

Safe retries

List jobs

Access after submission

​Submit and track a job

​Poll for completion

​Download results

​Output schemas

​Safe retries

​List jobs

​Access after submission

Submit and track a job

Poll for completion

Download results

Output schemas

Safe retries

List jobs

Access after submission