Some tools answer right away (synchronously); others start a job and finish it in the background. This page covers the second case: how to know a job is done and how to collect the result.
The create response
An async tool answers 202:
{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }
The state field is the same for every tool - rely on it:
| Value | Meaning |
|---|---|
pending | accepted, not started yet |
running | in progress |
action_required | waits for you (report review: confirm the extracted data) |
completed | done |
partial | done in part: some files failed (can happen to the content pack) |
failed | did not work |
status is the tool's raw status (DONE, processing, need_confirm and so on). It stays for compatibility; build new integrations on state.
Job id
Every job response, from any tool, carries the jobId field: on create, in the status and after confirmation. Poll the status with it.
Before version 1.6.0 tools returned the id under different names (id, _id, contentGenJobId). These fields are still returned for existing integrations but are deprecated: use jobId.
Polling
The status lives at GET /<tool path>/jobs/{id}:
| Tool | Status |
|---|---|
| Full valuation report | GET /valuation/report/jobs/{id} |
| Report review | GET /valuation/review/jobs/{id} |
| Content pack | GET /content/generate/jobs/{id} |
| Texts | GET /text/generate/jobs/{id} |
| Video | GET /video/create/jobs/{id} |
| Avatar | GET /avatar/video/jobs/{id} |
| Photo | GET /photo/enhance/jobs/{id} |
| Floor plan | GET /floorplan/create/jobs/{id} |
GET /pdf/create/jobs/{id} |
- Polling is free and is not counted as an API call, but it does count against the rate limit. Every 3-5 seconds is enough.
- Only the account whose key created the job can see it. Someone else's or an unknown id returns the same
404. - An agent-scoped agency key sees only the jobs it started; the agency-wide key sees all jobs of the agency.
- A job can be polled for 7 days after it was created. After that
GET .../jobs/{id}answers404, and content pack, text and video files can no longer be downloaded through the API. - The status response carries the same
statusandstateplus the tool's result once it is ready. A failed content pack, text or video job carrieserror, a photo jobmetadata.error- the reason as a generic text.
Floor plan and report review process the document right away: the 202 response already holds the final state (completed, failed or action_required), so polling is optional.
When a job waits for you
After reading the document, the report review (Valuation) stops in action_required and returns the extracted data in extracted. Check it and confirm:
curl -X POST https://developers.grem.capital/api/v1/valuation/review/jobs/JOB_ID/confirm \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{}'
An empty body means "all correct". To fix a value, send only the changed fields inside extracted, under the same names as in the response (the nested subject object is merged one level deep). The job then moves to running and the result arrives as usual.
Webhooks instead of polling
Every async tool sends a <tool>.completed or <tool>.failed event (the content pack also sends content.partial). Subscribing and verifying the signature: Webhooks.
- The event usually arrives within a minute after the job ends.
- A job is tracked only if a subscription to its event already existed when the job was created. Subscribe beforehand, not after starting the job.
- If a job has not finished within 30 minutes,
.failedarrives withreason: "timeout". The job itself may still finish - polling shows its real status.
Ready files
Files are downloaded through GET /artifacts/{path} with the same key (scope tools:artifacts). Free, supports Range. {path} is one of these:
| What | Path |
|---|---|
| A content pack, text or video file | v1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download |
| Avatar video | v1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download |
| PDF presentation | v1/ai/pdf-generator/files/{id}/download |
| Enhanced photo | v1/ai/photo-enhancement/jobs/{jobId}/download/{variant} |
| Full valuation report PDF | v1/ai/appraisal/reports/{id}/pdf |
| Rent estimate PDF | v1/ai/appraisal/rent/{id}/pdf |
| Review report | v1/ai/appraisal/reviews/{id}/report.pdf or report.docx |
| Floor plan report | v1/ai/floor-plan/jobs/{id}/report.pdf |
| Flyer file | v1/ai/flyer/file/{name} |
| Video track (preview) | v1/ai/video-generator/music/{trackId} |
| A regular file | the /files/... path from the tool response |
Content pack file ids are in the artifacts field of the job status. Content pack, text and video files are available only for jobs created through the API by the same account, for 7 days.
curl -L -o video.mp4 \
"https://developers.grem.capital/api/v1/artifacts/v1/ai/assistant/announcement/jobs/JOB_ID/artifacts/ARTIFACT_ID/download" \
-H "Authorization: Bearer gsk_live_xxx"
A PDF presentation also has a link field - the document's direct address.
Related
- Tools via API - which tools are synchronous and which are async.
- Webhooks - get results without polling.
- Files - uploading images for listings and tools.