---
title: "Poll transactions"
method: GET
path: "/api/stedi/2023-08-01/polling/transactions"
---

# Poll transactions

`GET /api/stedi/2023-08-01/polling/transactions`

## Request

- Base URL: `https://forecaster.cairhealth.com`
- URL: `https://forecaster.cairhealth.com/api/stedi/2023-08-01/polling/transactions`
- Auth: HTTP bearer

Stedi Core-compatible **Poll Transactions**. Returns transactions in ascending processing order so an incremental consumer can follow the stream without gaps.

Supply either `startDateTime` (initial poll) **or** `pageToken` (subsequent polls) — at least one is required. Unlike the list endpoint, polling **always** returns a `nextPageToken`, including on an empty page: when no new transactions are ready, the token re-encodes your current position rather than advancing the cursor, so no transaction can be skipped by a concurrent webhook or a delayed retry. Persist the token and pass it back on the next poll.

## Query parameters

- `pageSize` integer
- `pageToken` string
- `startDateTime` string, date-time

## Response `200`

A page of new transactions. `nextPageToken` is always present.

- StediPollTransactionsResponse
  - `items` StediTransactionSummary[], required
    - `transactionId` string, required: Unique transaction identifier.
    - `fileExecutionId` string, required: Identifier of the file execution the transaction belongs to.
    - `status` 'succeeded' | 'failed', required
    - `direction` 'INBOUND' | 'OUTBOUND' | 'UNKNOWN', required
    - `mode` 'test' | 'production' | 'other', required
    - `processedAt` string, date-time, required: When the transaction was processed, ISO 8601. For uploaded / EOB-converted X12 this is the historical check date from the X12 `GS04` header.
    - `artifacts` StediArtifact[], required: Downloadable artifacts. Only `input` and `output` artifacts are returned; URLs point back at Cair.
      - `artifactType` 'text/csv' | 'application/edifact' | 'application/filepart' | 'application/json' | 'application/pdf' | 'text/psv' | 'text/tsv' | 'application/edi-x12' | 'application/xml' | 'application/zip' | 'image/jpeg' | 'image/png' | 'image/tiff' | 'text/plain' | 'unknown', required: The MIME type of the artifact.
      - `usage` 'attachment' | 'input' | 'metadata' | 'output', required: The role the artifact plays in the transaction.
      - `sizeBytes` integer, required: Artifact size in bytes.
      - `url` string, required: Cair-hosted download URL. Following it returns a `302` to a presigned artifact URL.
      - `model` 'execution' | 'fragment' | 'transaction' | 'fault', required: The artifact model.
    - `partnership` StediPartnership, required: The EDI partnership the transaction was exchanged on.
      - `partnershipId` string, required: Partnership identifier, e.g. `local-clearinghouse`.
      - `partnershipType` 'x12' | 'edifact', required
      - `sender` object, required
        - `profileId` string, required
      - `receiver` object, required
        - `profileId` string, required
    - `x12` object
      - `metadata` StediX12Metadata, required: Metadata parsed from the X12 interchange, functional group, and transaction headers.
        - `interchange` object, required
          - `acknowledgmentRequestedCode` string, required: X12 `ISA14`.
          - `controlNumber` integer, required
        - `functionalGroup` object, required
          - `controlNumber` integer, required
          - `release` string, required: Implementation guide version, e.g. `005010X221A1`.
          - `date` string, required: `YYYY-MM-DD`.
          - `time` string, required: `HH:MM:SS`.
          - `functionalIdentifierCode` string, required: X12 `GS01`, e.g. `HC`, `HP`.
        - `transaction` object, required
          - `controlNumber` string, required
          - `transactionSetIdentifier` string, required: 3-digit X12 transaction set ID, e.g. `835`.
        - `sender` StediX12Profile, required
          - `applicationCode` string, required
          - `isa` object, required
            - `qualifier` string, required
            - `id` string, required
        - `receiver` StediX12Profile, required
          - `applicationCode` string, required
          - `isa` object, required
            - `qualifier` string, required
            - `id` string, required
      - `transactionSetting` object
        - `guideId` string
        - `transactionSettingId` string
    - `fragments` object
      - `keyName` string
      - `fragmentCount` integer
      - `batchSize` integer
    - `translationErrors` StediTranslationError[]: Details about errors that prevented Cair from processing the transaction.
      - `message` string, required
      - `context` object
        - `code` string
        - `schemaPath` string
      - `mark` object
        - `start` object
          - `line` integer, required
          - `column` integer, required
        - `end` object
          - `line` integer, required
          - `column` integer, required
    - `businessIdentifiers` StediBusinessIdentifier[]: Business identifiers extracted from the transaction.
      - `elementId` string, required: X12 element ID, e.g. `1028` or `127`.
      - `element` string, required: The element where the value was found, e.g. `CLP-01`.
      - `name` string, required: Human-readable name of the identifier.
      - `value` string, required: The identifier value.
  - `nextPageToken` string, required: Always present. Pass it back on the next poll. On an empty page it encodes your current position so no transactions are skipped.

## Other responses

- `400`: Invalid query parameter, cursor, or filter combination.
- `401`: Missing or invalid Cair access token.
- `500`: Unexpected server error while reading transactions.

## Changes

- **2026-11-03** `b32380ccde9a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cairhealth/apis/cair-health-apis/changes/api/stedi/2023-08-01/polling/transactions/get.md)

---

[API](https://skmtc.dev/cairhealth/apis/cair-health-apis.md) - [All operations](https://skmtc.dev/cairhealth/apis/cair-health-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/cairhealth/apis/cair-health-apis/revisions/b32380ccde9a?raw)