Polling and history

Polling a pending run

POST /v1/applications/{id}/executions returns 202 with an execution object whose status is QUEUED. Use its id as executionId in GET /v1/applications/{id}/executions/{executionId}, with the same connection access token. Poll every 3 to 5 seconds until the returned execution's status is COMPLETED or FAILED, then read its result or terminal.status. A run that reaches its time limit fails with timed_out.

There are no webhooks yet, so your product owns the polling loop. The Node script on the Quickstart shows one. You can still read executions with the existing token when their connection needs re-authorization.

Listing history

GET /v1/applications/{id}/executions lists the runs of the connection the token belongs to, newest first.

The response is { "executions": [...], "has_more": true }. Each row is the full execution object, result included, so one call is enough to render a history view. Keep requesting with after until has_more is false. This script pages through a connection's history two runs at a time. Set APPLICATION_ID to your application's id and ACCESS_TOKEN to the token from the connection's code exchange before running it:

#!/usr/bin/env bash
# List a connection's executions two at a time until the last page.
set -euo pipefail
API="${WOOL_API_ORIGIN:-https://api.trywool.com}"
after=""
while :; do
  page=$(curl -sS "$API/v1/applications/$APPLICATION_ID/executions?limit=2${after:+&after=$after}" \
    -H "Authorization: Bearer $ACCESS_TOKEN")
  echo "$page" | node -e 'const p=JSON.parse(require("fs").readFileSync(0,"utf8"));for(const e of p.executions)console.log(e.id,e.status,e.terminal?.status??"")'
  [ "$(echo "$page" | node -e 'process.stdout.write(String(JSON.parse(require("fs").readFileSync(0,"utf8")).has_more))')" = "true" ] || break
  after=$(echo "$page" | node -e 'const p=JSON.parse(require("fs").readFileSync(0,"utf8"));process.stdout.write(p.executions.at(-1).id)')
done

The history belongs to the connection, not the token, so a user who reconnects sees the same runs through their new token.

Next steps

Handling failures tells you what to do when a poll comes back FAILED.