Skip to main content
GET
/
api
/
jobs
/
:id
Get Job Status
curl --request GET \
  --url https://api.example.com/api/jobs/:id
{
  "400": {},
  "401": {},
  "404": {},
  "id": "<string>",
  "type": "<string>",
  "status": "<string>",
  "result": {},
  "error": "<string>",
  "attempts": 123,
  "createdAt": "<string>",
  "startedAt": "<string>",
  "completedAt": "<string>",
  "updatedAt": "<string>"
}
Polls the status of an asynchronous background job (e.g. AI preview via Bedrock). Returns the job record including status and result payload.

​
Authentication

Requires JWT Bearer token (Cognito). Jobs are scoped to the requesting user — you cannot access other users’ jobs.

​
Path Parameters

​
id
string
required
Job UUID returned from the job-creating endpoint (e.g. POST /api/admin/prompts/preview)Format: UUIDExample: 550e8400-e29b-41d4-a716-446655440000

​
Response

​
id
string
Job UUID
​
type
string
Job type enum valueValues: AI_PREVIEW, PARSE_DOCUMENT, GAP_DETECTION, RISK_ANALYSIS, REPORT_GENERATION
​
status
string
Current job statusValues: PENDING, PROCESSING, COMPLETED, FAILEDPoll every 3 seconds until status is COMPLETED or FAILED
​
result
object
Output from the worker Lambda when status is COMPLETED. Structure varies by job type.For AI_PREVIEW jobs:
  • output (string): The AI-generated preview text
​
error
string
Error message if status is FAILED
​
attempts
number
Number of processing attempts (max 3 retries)
​
createdAt
string
ISO 8601 timestamp when the job was created
​
startedAt
string
ISO 8601 timestamp when processing started
​
completedAt
string
ISO 8601 timestamp when the job completed or failed
​
updatedAt
string
ISO 8601 timestamp of last status update

​
Example Request

curl -X GET https://api.example.com/api/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Example Response (Completed)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "AI_PREVIEW",
  "status": "COMPLETED",
  "result": {
    "output": "The main market risks identified are price volatility, lack of market access, and limited contract farming opportunities. Recommendations include establishing farmer cooperatives, diversifying market channels, and implementing price risk management strategies."
  },
  "error": null,
  "attempts": 1,
  "createdAt": "2026-03-04T12:00:00.000Z",
  "startedAt": "2026-03-04T12:00:01.000Z",
  "completedAt": "2026-03-04T12:00:05.000Z",
  "updatedAt": "2026-03-04T12:00:05.000Z"
}

​
Example Response (Processing)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "AI_PREVIEW",
  "status": "PROCESSING",
  "result": null,
  "error": null,
  "attempts": 1,
  "createdAt": "2026-03-04T12:00:00.000Z",
  "startedAt": "2026-03-04T12:00:01.000Z",
  "completedAt": null,
  "updatedAt": "2026-03-04T12:00:02.000Z"
}

​
Example Response (Failed)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "AI_PREVIEW",
  "status": "FAILED",
  "result": null,
  "error": "Bedrock API error: ThrottlingException - Rate exceeded",
  "attempts": 3,
  "createdAt": "2026-03-04T12:00:00.000Z",
  "startedAt": "2026-03-04T12:00:01.000Z",
  "completedAt": "2026-03-04T12:00:15.000Z",
  "updatedAt": "2026-03-04T12:00:15.000Z"
}

​
Error Responses

​
400
error
Invalid UUID format
​
401
error
Missing or invalid Bearer token
​
404
error
Job not found or does not belong to the requesting user

​
Source Code

Implementation: packages/api/src/jobs/jobs.controller.ts:19

Build docs developers (and LLMs) love

Get started for freeTalk to us