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
review
approved
synced
rejected
cancelled
failed

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 webhook URL was configured
`pending`	Delivery is queued or retrying
`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 & Jobs

On this page