Jobs
Jobs are created by domain endpoints (/v1/reports/jobs, /v1/matching-analysis/jobs).
Generated from contracts in
packages/contracts/src/v1. Do not hand-edit this page.
GET /v1/jobs/:jobId
Get current lifecycle state for a job.
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "report.generate"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"reportId": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsUsed": {
"type": "number"
},
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsUsed",
"creditsNetUsed"
],
"additionalProperties": false
},
"credits": {
"type": "object",
"properties": {
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
}
},
"required": [
"reservedCredits",
"reservationStatus"
],
"additionalProperties": false
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"id",
"type",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
GET /v1/jobs/:jobId/stream
Server-Sent Events stream for real-time job updates.
- Events include
status,stage,terminal, andheartbeat. - Use
Last-Event-IDheader to resume dropped streams.
Query schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"timeout": {
"default": 300000,
"description": "Stream timeout in milliseconds (default: 300000, max: 300000)",
"type": "number",
"minimum": 1000,
"maximum": 300000
}
},
"required": [
"timeout"
],
"additionalProperties": false
}
Stream event schemas
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Monotonically increasing event ID for resumption"
},
"event": {
"type": "string",
"const": "status"
},
"data": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "report.generate"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"reportId": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsUsed": {
"type": "number"
},
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsUsed",
"creditsNetUsed"
],
"additionalProperties": false
},
"credits": {
"type": "object",
"properties": {
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
}
},
"required": [
"reservedCredits",
"reservationStatus"
],
"additionalProperties": false
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"id",
"type",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
},
"required": [
"status",
"job"
],
"additionalProperties": false
}
},
"required": [
"id",
"event",
"data"
],
"additionalProperties": false
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Monotonically increasing event ID for resumption"
},
"event": {
"type": "string",
"const": "stage"
},
"data": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "report.generate"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"reportId": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsUsed": {
"type": "number"
},
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsUsed",
"creditsNetUsed"
],
"additionalProperties": false
},
"credits": {
"type": "object",
"properties": {
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
}
},
"required": [
"reservedCredits",
"reservationStatus"
],
"additionalProperties": false
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"id",
"type",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
},
"required": [
"stage",
"job"
],
"additionalProperties": false
}
},
"required": [
"id",
"event",
"data"
],
"additionalProperties": false
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Monotonically increasing event ID for resumption"
},
"event": {
"type": "string",
"const": "terminal"
},
"data": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"succeeded",
"failed",
"canceled"
]
},
"reportId": {
"type": "string"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"job": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "report.generate"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"reportId": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsUsed": {
"type": "number"
},
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsUsed",
"creditsNetUsed"
],
"additionalProperties": false
},
"credits": {
"type": "object",
"properties": {
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
}
},
"required": [
"reservedCredits",
"reservationStatus"
],
"additionalProperties": false
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"id",
"type",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}
},
"required": [
"status",
"job"
],
"additionalProperties": false
}
},
"required": [
"id",
"event",
"data"
],
"additionalProperties": false
}
POST /v1/jobs/:jobId/cancel
Cancel a queued or running job.
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "report.generate"
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"progress": {
"type": "number"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"reportId": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsUsed": {
"type": "number"
},
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsUsed",
"creditsNetUsed"
],
"additionalProperties": false
},
"credits": {
"type": "object",
"properties": {
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
}
},
"required": [
"reservedCredits",
"reservationStatus"
],
"additionalProperties": false
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"id",
"type",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
}