Poll Executions

Poll for new file executions that Stedi has recently processed.

GET /polling/executions

This endpoint returns file executions that Stedi processed after the specified startDateTime.

Executions are ordered from oldest to newest according to the processedAt property. This is exclusive of the startDateTime. For example, if the provided startDateTime is 2023-08-10T18:00:00Z, an execution processed at exactly that time would not be included in the results. There is also a fifteen-second window where newly created executions are excluded, meaning Stedi returns results up to fifteen seconds before the time of your request. This functionality accounts for any network latency or clock drift within the systems to ensure you don't miss any executions.

Polling with page tokens

We don't recommend polling using startDateTime only. Due to the exclusive nature of startDateTime, you could potentially miss an execution if two executions occur at the exact same time and are on the edge of a pagination. Instead, you should use pageToken.

After the initial request, you can poll again immediately using pageToken to continue iterating through the pages of executions. The endpoint always returns a nextPageToken, regardless of whether additional executions match the request criteria. If the items array is empty, continue using the provided nextPageToken to poll for new executions. New executions will be returned when available.

We recommend storing pageToken values as part of your polling process. They don't expire, allowing you to start from that point in the execution stream again if you need to catch a system up to date or recover from a failure.

Note that pageToken values are unique per request, opaque, and shouldn't be parsed or modified in any way. They are not guaranteed to be in any particular format, and may change in the future.

Authorizations

Authorization · Required Header

A Stedi API Key for authentication.

Query Parameters

pageSize · Number Range: ≥ 1

The maximum number of elements to return in a page. You can set this to a maximum of 500 elements. If not specified, the default is 100.

pageToken · String Length: 1 - 1024

A token returned by a previous call to this operation in the nextPageToken. If not specified, Stedi returns the first page of results.

You must supply either this property or startDateTime in every request.

startDateTime · String Format: date-time

An ISO 8601 formatted string. For example 2023-08-28T00:00:00Z. Stedi returns executions processed after this time.

You must supply either this property or pageToken in every request. The startDateTime must be at least one minute in the past.

Response

application/json

ListPollingExecutions 200 response

nextPageToken · String Length: 1 - 1024

Token for pagination to retrieve the next page of results; null if there are no more results

items · Array of Objects Required

The processed executions that match the request criteria. The items array is empty if there are no matching executions.

createdAt · items[].createdAt · String Required Format: date-time

The date and time when the resource was created, in ISO 8601 format. For example, 2023-08-28T00:00:00Z.

updatedAt · items[].updatedAt · String Required Format: date-time

The date and time when the resource was last updated, in ISO 8601 format. For example, 2023-08-28T00:00:00Z.

executionId · items[].executionId · String Required

A unique identifier for the processed file within Stedi. This ID is included in the transaction processed event. You can also retrieve it manually from the file's details page in the Stedi portal.

status · items[].status · String Required

The status of the execution. An execution is COMPLETED when Stedi has finished processing the file with no errors. If the file is an outbound file, a COMPLETED status also means that Stedi successfully delivered it to the configured connection.

Possible values

COMPLETED

PARTIALLY_COMPLETED

FAILED

IGNORED

IN_PROGRESS

direction · items[].direction · String Required

The direction of the transaction. Inbound transactions are those you receive from a payer, provider, or other trading partner. Outbound transactions are those you send to a payer, provider, or other trading partner.

Possible values

INBOUND

OUTBOUND

UNKNOWN

transactionCount · items[].transactionCount · Number

The number of individual transactions included in the file.

faultCount · items[].faultCount · Number

The number of errors that occurred during processing. If the file was successfully processed completely, this value is 0.

faultCode · items[].faultCode · String

A code specifying the reason for the fault.

Possible values

DELIVERY_FAILURE

FAILED_TO_EXTRACT_BUSINESS_IDENTIFIERS

FAILED_TO_FIND_GUIDE

FAILED_TO_FIND_LOCAL_PROFILE

FAILED_TO_FIND_PARTNER_PROFILE

faultMessage · items[].faultMessage · String

A message providing more information about the fault. Note that if there are multiple faults, Stedi sets the first fault as the code and corresponding message.

fileType · items[].fileType · String

The file format. For example, EDI/EDIFACT for an EDIFACT file or EDI/X12 for an X12 EDI file.

Possible values

CSV

EDI/EDIFACT

FILEPART

JSON

PSV

retryable · items[].retryable · Boolean

If true, you can retry the file in the Stedi portal.

parentExecutionId · items[].parentExecutionId · String

The ID of this execution's parent execution, if it is part of a retry chain. When you retry a file, Stedi creates a child execution with a new ID and links it to the original (parent) execution.

childExecutionId · items[].childExecutionId · String

The ID of this execution's child execution, if it is part of a retry chain. When you retry a file, Stedi creates a child execution with a new ID and links it to the original (parent) execution.

partnershipId · items[].partnershipId · String Regex pattern: ^([a-zA-Z0-9._-]+)$ Length: 1 - 81

The unique identifier for the partnership within the Stedi platform.

A partnership describes all aspects of the EDI relationship between two profiles in your Stedi account, such as which transaction sets they will exchange and other important information for processing EDI files.

connectionType · items[].connectionType · String

The type of connection used for exchanging files.

Possible values

bucket

remote-ftp

stedi-ftp

as2

connectionId · items[].connectionId · String Regex pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$

An autogenerated identifier for the connection within the Stedi platform.

source · items[].source · Object

The source of the file, including the directory where Stedi received it and the file name.

dirname · items[].source.dirname · String Required

The directory where Stedi received the file for processing.

name · items[].source.name · String Required

The name of the file.

cURL

curl --request GET \
  --url "https://core.us.stedi.com/2023-08-01/polling/executions?pageSize=200" \
  --header "Authorization: <api_key>"

JavaScript

fetch("https://core.us.stedi.com/2023-08-01/polling/executions?pageSize=200", {
  headers: {
    "Authorization": "<api_key>"
  }
})

Go

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://core.us.stedi.com/2023-08-01/polling/executions?pageSize=200"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", "<api_key>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

Python

import requests

url = "https://core.us.stedi.com/2023-08-01/polling/executions?pageSize=200"

response = requests.request("GET", url, headers = {
  "Authorization": "<api_key>"
})

print(response.text)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;

HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://core.us.stedi.com/2023-08-01/polling/executions?pageSize=200"))
  .header("Authorization", "<api_key>")
  .GET()
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

200

{
  "items": [
    {
      "createdAt": "2025-04-04T17:14:35.481Z",
      "direction": "INBOUND",
      "executionId": "55907f88-999e-4912-9e9b-78326f8bade8",
      "faultCount": 0,
      "partnershipId": "local-clearinghouse-test",
      "source": {
        "dirname": ".",
        "name": "test-inbound-ingest-30848232-fa0c-4151-8217-d03205e806f9.edi"
      },
      "retryable": true,
      "status": "COMPLETED",
      "transactionCount": 1,
      "updatedAt": "2025-04-04T17:14:42.854Z"
    },
    {
      "createdAt": "2025-04-02T21:30:08.387Z",
      "direction": "INBOUND",
      "executionId": "95236a56-a020-4522-8fef-bcffcec0ec1d",
      "faultCount": 0,
      "partnershipId": "local-clearinghouse-test",
      "source": {
        "dirname": ".",
        "name": "test-inbound-ingest-3f2efd94-2a81-4b57-b4de-9b970a50db60.edi"
      },
      "retryable": true,
      "status": "COMPLETED",
      "transactionCount": 1,
      "updatedAt": "2025-04-02T21:30:16.185Z"
    },
    {
      "createdAt": "2025-02-28T19:16:26.041Z",
      "direction": "OUTBOUND",
      "executionId": "06bdccdc-4ab9-4add-b1dc-a76a0183f299",
      "faultCount": 0,
      "partnershipId": "local-clearinghouse-test",
      "source": {
        "dirname": ".",
        "name": "837-clearinghouse_outbound.edi"
      },
      "retryable": true,
      "status": "COMPLETED",
      "transactionCount": 1,
      "updatedAt": "2025-02-28T19:16:27.706Z"
    }
  ],
  "nextPageToken": "eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MTAsInBhZ2VUb3RhbCI6MzE0fQ=="
}

400

{
  "message": "string",
  "code": "string"
}

401

{
  "message": "string",
  "code": "string"
}

403

{
  "message": "string",
  "code": "string"
}

404

{
  "message": "string",
  "code": "string"
}

409

{
  "message": "string"
}

429

{
  "message": "string",
  "code": "string"
}

500

{
  "message": "string",
  "cause": {
    "name": "string",
    "message": "string",
    "stack": "string"
  }
}

503

{
  "message": "string",
  "code": "string"
}

504

{
  "message": "string",
  "code": "string"
}