Polling & Jobs

How Steve represents asynchronous workflow progress and what to read from the polling endpoint.

GET /api/v1/jobs/{sessionId} is the polling endpoint for asynchronous workflow sessions.

It answers a different question from GET /api/v1/submissions/{submissionId}:

the job endpoint tells you where the session is in its async lifecycle
the submission endpoint gives you the canonical review-state read model

Endpoint

GET /api/v1/jobs/{sessionId}
Authorization: Bearer aok_<key>

The session must belong to the same API key.

Workflow-session response

{
  "sessionId": "jx7ses789session",
  "submissionId": "jx7sub456submissions",
  "workflow": {
    "slug": "receipt-ocr",
    "version": 3
  },
  "companyId": "jx7abc123company",
  "state": "completed",
  "submissionStatus": "review",
  "result": {
    "extractedData": {
      "merchantName": "Biedronka",
      "totalAmount": 123.45,
      "currency": "PLN"
    },
    "confidence": 0.96,
    "fraudStatus": "flagged"
  },
  "failedReason": null,
  "clientSubmissionId": "order-1711353600000",
  "metadata": {
    "orderId": "12345"
  },
  "processedAt": "2026-03-25T10:05:30.000Z",
  "webhookDeliveryStatus": "delivered"
}

Field meanings

Field	Meaning
`state`	Session lifecycle status
`submissionStatus`	Current public submission status when known
`result`	Workflow-specific extraction payload
`failedReason`	Processing failure reason when `state=failed`
`processedAt`	ISO completion timestamp when available
`webhookDeliveryStatus`	Delivery state for the configured production webhook

For a newly created or still-running session, result, submissionStatus, and processedAt may be null.

Status values

Status	Meaning	Terminal
`pending`	Session exists but has not been submitted	No
`submitted`	Session has been queued or is actively processing	No
`completed`	Processing finished	Yes
`failed`	Processing failed	Yes
`expired`	Session timed out before submit	Yes

Submission status values

When Steve has a linked submission, submissionStatus can be:

created
processing
capture_quality_blocked
review
approved
synced
rejected
cancelled
failed

capture_quality_blocked means processing stopped because the uploaded capture did not meet quality requirements. This is the field to use when you need to know whether a completed session requires manual review.

Expiration model

Sessions are created with a 30-minute TTL. Expiration is finalized by a background sweep, so a stale unsubmitted session can remain pending briefly before it is marked expired.

Webhook delivery status

Value	Meaning
`null`	No delivery attempt is recorded yet, either because no webhook was configured or because the configured webhook has not yet been attempted
`pending`	A delivery attempt failed and a retry is scheduled
`delivered`	A target returned `2xx`
`failed`	Delivery exhausted its retry budget

Recommended polling pattern

poll every 5 to 10 seconds
stop when state is completed, failed, or expired
if state=completed and submissionStatus=review, fetch the submission and enter your review flow
if webhooks are enabled, keep polling as a fallback and recovery path rather than the primary notification channel

Polling bulk uploads

When you create many sessions with the same batchRef, poll the batch aggregate instead of each job individually:

GET /api/v1/batches/{batchRef}
Authorization: Bearer aok_<key>

The response reports counts (total, processed, review, failed, approved) and a status of open or completed. Per-job polling remains available for drilling into individual sessions, but one batch request replaces thousands of job requests during a bulk import. See the batch endpoint reference and the batch.completed event in webhooks.

Polling & Jobs

On this page