Docs

Start here

How is my job doing

GET/v1/jobs/{id}on https://api.auray.ai/v1

Read one job, reconciling it first where that is possible.

Read one job, reconciling it first where that is possible. Photo, music and 3D are polled against their own service, so this is the call that turns a stale row into a settled one. VIDEO AND CHAT ARE NOT POLLED and deliberately so — video settles from its callback and chat from the turn itself, so for those two this reports what is already stored. poll_after_seconds is present only while the job is unsettled, so a loop can stop on its absence rather than on a status it has to interpret. A job is kept three days: after that its request and its results are deleted and this answers 404, so fetch what you need before then.

#Authentication

Authorization: Bearer auray_sk_… — jobs:read.

#Request

#Path parameters

NameTypeRequiredDescription
idstringyes

#Query parameters

NameTypeRequiredDescription
include_reasoningstringnoChat only. Reasoning often runs several times the length of the answer. One of "true".

#Example request

curl https://api.auray.ai/v1/jobs/photo_docs-mtpb1vnh \
  -H "Authorization: Bearer $AURAY_API_KEY"

#Responses

#200 OK

OK

FieldTypeRequiredDefaultDescription
idstringyes—
job_idstringyes—The job's one id on every host: id here, request_id on the queue host (the queue protocol's name for it).
objectstringyes—One of "job".
productstringyes—external covers every model somebody else runs, each at its own address. chat is accepted and delivers no webhook event: a chat turn is answered by the request that paid for it. One of "photo", "music", "video", "threed", "chat", "external".
modelstringyes—The address the job was submitted to. May be null.
enginestringyes—The service's own name for the model that ran, where it reports one — a catalogue model's is its id on GET /v1/models — as the submit answered it; null otherwise. May be null.
statusstringyes—Five words, whatever the product. Our internals disagree; you never see that. One of "queued", "running", "succeeded", "failed", "cancelled".
provider_job_idstringyes—May be null.
credits_chargedintegeryes—What the job cost, after any refund — the ledger's net for it, the same figure on every door.
credits_reservedintegeryes—What was held against the worst case before the model ran. Chat jobs only; absent on every other product.
coverageobjectno—Present when a pass or a promotion paid for this job, which is why credits_charged is 0: {"by": "pass", "pass": "seedance-2-5"} names the pass (null when the grant ended more than seven days ago), {"by": "promotion"} a promotion. Absent on a job your credits paid for.
coverage.bystringyes—One of "pass", "promotion".
coverage.passstringno—May be null.
settledbooleanyes—
poll_after_secondsintegerno—
give_up_after_secondsintegerno—Present while the job is open: the longest it may take, counted from created_at — the longest it may wait to start plus the longest it may run before it is stopped and refunded, the figure its submit answered. Waiting longer is waiting for nothing; the official clients wait this long by default. For a catalogue model the part it may run is its own reap as its registry row states it (lifecycle.stall_ceiling_seconds on GET /v1/models); otherwise these are the shipped clocks: we may lengthen them in an incident, never shorten them.
assetsobject[]yes—
assets[].indexintegerno—
assets[].kindstringno—One of "image", "audio", "video", "model".
assets[].keystringno—May be null.
assets[].bytesintegerno—May be null.
assets[].widthintegerno—May be null.
assets[].heightintegerno—May be null.
assets[].stagestringno—3D only.
assets[].secondsnumberno—Audio and video assets: the real duration, once known. May be null.
assets[].sample_rateintegerno—Audio assets only. May be null.
assets[].channelsintegerno—Audio assets only. May be null.
assets[].fpsnumberno—Video assets only: frames per second, once known. May be null.
assets[].resolutionstringno—Video assets only: the rendered resolution, as the service reports it. May be null.
assets[].has_audiobooleanno—Video assets only: whether the clip carries a soundtrack. May be null.
assets[].seedintegerno—Our video's clips only: the seed the clip rendered with. Send it back as seed with the same prompt and settings to render the same clip. May be null.
request_idstringyes—
conversation_idstringno—The thread this turn belongs to. Chat jobs only; absent on every other product.
contentstringno—The answer text. Chat jobs only; absent on every other product.
finish_reasonstringno—Why generation stopped. Chat jobs only; absent on every other product. Null until the turn settles, and on a turn that stopped before reporting. May be null.
usageobjectno—Token counts for the turn. Chat jobs only; absent on every other product. Every count is null until the turn settles — and stays null on a turn that was stopped or failed, because the usage frame routinely never arrives.
usage.prompt_tokensintegerno—May be null.
usage.cached_prompt_tokensintegerno—May be null.
usage.completion_tokensintegerno—May be null.
usage.reasoning_tokensintegerno—May be null.
reasoningstringno—The model's reasoning, present only when include_reasoning=true was asked for. Often several times the length of the answer. Chat jobs only; absent on every other product.
created_atstringyes—When the job was submitted.
errorstringyes—Why it failed, as a sentence: the model's own words where it gave them, ours otherwise. Null unless it did. May be null.
error_codestringyes—A stable code for the same failure, where the service gives one. May be null.
refusedintegerno—How many images the safety filter withheld. Photo only; absent on every other product. 0 to ….
upstream_lostbooleanno—Present, and only ever true, when the rendering service no longer has any record of this job. It keeps them for a few days, so an old id reads the same as one that never existed. Absent otherwise. One of true.

Headers:

HeaderDescription
RateLimit-LimitBurst capacity.
RateLimit-Remaining
RateLimit-ResetSeconds until refill.
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-ResetUnix seconds. The X- spelling is what client libraries read.
X-Request-Id

#401 Unauthorized

#403 Forbidden

#404 Not Found

#429 Too Many Requests

#500 Internal Server Error

job_read_failed — your job could not be read. It does not say the job is missing: a failed lookup used to answer 404 not_found, which asserts the id is wrong or not yours, and neither had been established. Retry; the job is untouched.

The error body: error, message, docs (the entry that explains it) and request_id.

#503 Service Unavailable

#Status codes

StatusMeaning
200OK
401Unauthorized
403Forbidden
404Not Found
429Too Many Requests
500job_read_failed — your job could not be read.
503Service Unavailable

Every refusal names its code, and every code is explained at Errors.

Start typing to search every page of the documentation.

Up arrow Down arrow to moveEnter to openEscape to close