Jobs
Jobs are created by domain endpoints (/v1/reports/jobs, /v1/matching/jobs).
Schemas are generated from the API contract. Examples and guide links are maintained to stay aligned with the live API. Do not hand-edit this page.
GET /v1/jobs/:jobId
Get current lifecycle state for a job.
Usage notes
- Use
receipt.jobIdas the durable correlation key while a report or matching job is running. - Production apps usually finish on verified webhooks; polling is the fallback when you cannot expose a webhook endpoint.
Request example
curl https://api.mappa.ai/v1/jobs/job_abc123 \
-H "Mappa-Api-Key: $CONDUIT_API_KEY"
Response examples
Running job
{
"id": "job_abc123",
"type": "report.generate",
"status": "running",
"stage": "rendering",
"progress": 0.82,
"createdAt": "2026-03-23T12:01:00.000Z",
"updatedAt": "2026-03-23T12:02:10.000Z"
}
Terminal failure
{
"id": "job_abc123",
"type": "report.generate",
"status": "failed",
"error": {
"code": "target_not_found",
"message": "Could not identify target speaker",
"retryable": false
},
"createdAt": "2026-03-23T12:01:00.000Z",
"updatedAt": "2026-03-23T12:02:30.000Z"
}
Common errors
404 not_found- ThejobIddoes not exist in the authenticated workspace.
Related guides
- Direct API workflow - Upload -> create job -> complete async work with current REST examples.
- Webhooks - Signature verification, delivery semantics, and production handler patterns.
- Error codes - HTTP statuses, billing failures, and removed-surface migration notes.
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"credits": {
"type": "object",
"properties": {
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
},
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"reservationStatus",
"reservedCredits"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"details": {},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"matchingId": {
"type": "string"
},
"progress": {
"type": "number"
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reportId": {
"type": "string"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"type": {
"type": "string",
"enum": [
"report.generate",
"matching.generate"
]
},
"updatedAt": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"creditsUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsNetUsed",
"creditsUsed"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"status",
"type",
"updatedAt"
],
"additionalProperties": false
}
GET /v1/jobs/:jobId/stream
Server-Sent Events stream for real-time job updates.
Usage notes
- Events include
status,stage,terminal, andheartbeat. - Use
Last-Event-IDheader to resume dropped streams. - Use this for controlled clients and internal tooling; webhooks remain the preferred production completion path.
Request example
curl -N "https://api.mappa.ai/v1/jobs/job_abc123/stream?timeout=300000" \
-H "Mappa-Api-Key: $CONDUIT_API_KEY" \
-H "Accept: text/event-stream"
Response example
Status event
event: status
id: evt_0001
data: {"status":"running","stage":"extracting","progress":0.42,"job":{"id":"job_abc123","type":"report.generate","status":"running","stage":"extracting","createdAt":"2026-03-23T12:01:00.000Z","updatedAt":"2026-03-23T12:01:05.000Z"}}
Related guides
- Webhooks - Signature verification, delivery semantics, and production handler patterns.
- Direct API workflow - Upload -> create job -> complete async work with current REST examples.
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"
},
"data": {
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"credits": {
"type": "object",
"properties": {
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
},
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"reservationStatus",
"reservedCredits"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"details": {},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"matchingId": {
"type": "string"
},
"progress": {
"type": "number"
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reportId": {
"type": "string"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"type": {
"type": "string",
"enum": [
"report.generate",
"matching.generate"
]
},
"updatedAt": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"creditsUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsNetUsed",
"creditsUsed"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"status",
"type",
"updatedAt"
],
"additionalProperties": false
},
"progress": {
"type": "number"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
}
},
"required": [
"job",
"status"
],
"additionalProperties": false
},
"event": {
"type": "string",
"const": "status"
}
},
"required": [
"id",
"data",
"event"
],
"additionalProperties": false
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Monotonically increasing event ID for resumption"
},
"data": {
"type": "object",
"properties": {
"job": {
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"credits": {
"type": "object",
"properties": {
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
},
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"reservationStatus",
"reservedCredits"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"details": {},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"matchingId": {
"type": "string"
},
"progress": {
"type": "number"
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reportId": {
"type": "string"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"type": {
"type": "string",
"enum": [
"report.generate",
"matching.generate"
]
},
"updatedAt": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"creditsUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsNetUsed",
"creditsUsed"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"status",
"type",
"updatedAt"
],
"additionalProperties": false
},
"progress": {
"type": "number"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
}
},
"required": [
"job",
"stage"
],
"additionalProperties": false
},
"event": {
"type": "string",
"const": "stage"
}
},
"required": [
"id",
"data",
"event"
],
"additionalProperties": false
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Monotonically increasing event ID for resumption"
},
"data": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"job": {
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"credits": {
"type": "object",
"properties": {
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
},
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"reservationStatus",
"reservedCredits"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"details": {},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"matchingId": {
"type": "string"
},
"progress": {
"type": "number"
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reportId": {
"type": "string"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"type": {
"type": "string",
"enum": [
"report.generate",
"matching.generate"
]
},
"updatedAt": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"creditsUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsNetUsed",
"creditsUsed"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"status",
"type",
"updatedAt"
],
"additionalProperties": false
},
"matchingId": {
"type": "string"
},
"reportId": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"succeeded",
"failed",
"canceled"
]
}
},
"required": [
"job",
"status"
],
"additionalProperties": false
},
"event": {
"type": "string",
"const": "terminal"
}
},
"required": [
"id",
"data",
"event"
],
"additionalProperties": false
}
POST /v1/jobs/:jobId/cancel
Cancel a queued or running job.
Request example
curl -X POST https://api.mappa.ai/v1/jobs/job_abc123/cancel \
-H "Mappa-Api-Key: $CONDUIT_API_KEY"
Response example
{
"id": "job_abc123",
"type": "report.generate",
"status": "canceled",
"createdAt": "2026-03-23T12:01:00.000Z",
"updatedAt": "2026-03-23T12:01:15.000Z"
}
Common errors
409- Only queued or running jobs are cancelable on this surface.
Related guides
- Direct API workflow - Upload -> create job -> complete async work with current REST examples.
- Error codes - HTTP statuses, billing failures, and removed-surface migration notes.
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"credits": {
"type": "object",
"properties": {
"reservationStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"active",
"released",
"applied"
]
},
{
"type": "null"
}
]
},
"reservedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"reservationStatus",
"reservedCredits"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"details": {},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"matchingId": {
"type": "string"
},
"progress": {
"type": "number"
},
"releasedCredits": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"reportId": {
"type": "string"
},
"stage": {
"type": "string",
"enum": [
"uploaded",
"queued",
"transcoding",
"extracting",
"scoring",
"rendering",
"finalizing"
]
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"succeeded",
"failed",
"canceled"
]
},
"type": {
"type": "string",
"enum": [
"report.generate",
"matching.generate"
]
},
"updatedAt": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"creditsDiscounted": {
"type": "number"
},
"creditsNetUsed": {
"type": "number"
},
"creditsUsed": {
"type": "number"
},
"durationMs": {
"type": "number"
},
"modelVersion": {
"type": "string"
}
},
"required": [
"creditsNetUsed",
"creditsUsed"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"status",
"type",
"updatedAt"
],
"additionalProperties": false
}