How to Monitor Account and Group Health via API

Use this tutorial to build a polling script that lists all groups in your account, retrieves the connections in each group, and inspects each connection's sync and setup state.

Prerequisites

You have a scoped API key and secret.
You have jq installed.

Instructions

Set your environment variables.
List all groups.
List connections in a group.
Get connection details.
Review polling cadence recommendations.

Set your environment variables

export FIVETRAN_API_KEY="<your_api_key>"
export FIVETRAN_API_SECRET="<your_api_secret>"
export FIVETRAN_BASE_URL="https://api.fivetran.com/v1"
export FIVETRAN_AUTH_HEADER=$(printf "%s" "$FIVETRAN_API_KEY:$FIVETRAN_API_SECRET" | base64 | tr -d '\n')

List all groups

Use the List All Groups endpoint to retrieve an inventory of all groups in your account.

LIST_GROUPS_RESPONSE=$(curl --silent --show-error \
  --request GET \
  --url "$FIVETRAN_BASE_URL/groups" \
  --header "Accept: application/json" \
  --header "Authorization: Basic $FIVETRAN_AUTH_HEADER")

echo "$LIST_GROUPS_RESPONSE" | jq '.data.items[] | {id: .id, name: .name}'

The response includes an items array. Each item contains the group id and name. Store any group IDs you want to inspect:

export GROUP_ID=$(echo "$LIST_GROUPS_RESPONSE" | jq -r '.data.items[0].id')
echo "GROUP_ID=$GROUP_ID"

The GET /v1/groups endpoint returns paginated results. If your account has many groups, use the cursor field in the response to fetch subsequent pages.

List connections in a group

Use the List All Connections in Group endpoint to retrieve the connections and their current status for a given group.

LIST_CONNECTIONS_RESPONSE=$(curl --silent --show-error \
  --request GET \
  --url "$FIVETRAN_BASE_URL/groups/$GROUP_ID/connections" \
  --header "Accept: application/json" \
  --header "Authorization: Basic $FIVETRAN_AUTH_HEADER")

echo "$LIST_CONNECTIONS_RESPONSE" | jq '.data.items[] | {id: .id, service: .service, sync_state: .status.sync_state, setup_state: .status.setup_state}'

The response includes a status object for each connection. Key fields are:

Field	Description
`status.sync_state`	Current sync state. Possible values: `scheduled`, `syncing`, `paused`, `rescheduled`.
`status.setup_state`	Setup completion state. Possible values: `connected`, `incomplete`, `broken`.
`paused`	Whether the connection is currently paused.

Get connection details

Use the Retrieve Connection Details endpoint to inspect the full state of a single connection, including failed_at and succeeded_at timestamps.

export CONNECTION_ID="<your_connection_id>"

GET_CONNECTION_RESPONSE=$(curl --silent --show-error \
  --request GET \
  --url "$FIVETRAN_BASE_URL/connections/$CONNECTION_ID" \
  --header "Accept: application/json" \
  --header "Authorization: Basic $FIVETRAN_AUTH_HEADER")

echo "$GET_CONNECTION_RESPONSE" | jq '.data | {
  id: .id,
  service: .service,
  sync_state: .status.sync_state,
  setup_state: .status.setup_state,
  failed_at: .failed_at,
  succeeded_at: .succeeded_at,
  paused: .paused
}'

Interpreting the health fields

Field	What to look for
`status.setup_state`	`broken` indicates the connection can no longer connect to the source. Credentials or network configuration may need updating.
`status.sync_state`	`rescheduled` may indicate a transient error. Persistent `rescheduled` state warrants investigation.
`failed_at`	Timestamp of the last failed sync. Compare against `succeeded_at` to determine how long a connection has been unhealthy.
`succeeded_at`	Timestamp of the last successful sync. A large gap between `succeeded_at` and the current time may indicate a stalled connection.

Connection-level status fields (sync_state, setup_state, failed_at, succeeded_at) are available from both the list and single-connection endpoints. Use the list endpoint for a broad sweep across a group, and the single-connection endpoint when you need to drill into a specific connection.

A connection with setup_state: broken will not sync until the underlying issue is resolved. Use the Run Connection Setup Tests endpoint after fixing credentials or network configuration to confirm the connection is healthy before re-enabling syncs.

Polling cadence

Poll GET /v1/groups/{groupId}/connections or GET /v1/connections/{connectionId} every 5–10 minutes for routine health monitoring. Polling more frequently than once per minute is not recommended and may result in rate limiting.

For event-driven alerting instead of scheduled polling, use webhooks. Fivetran can deliver sync_start, sync_end, and connection_status_changed events to your endpoint in real time, eliminating the need to poll.

Endpoints used in this workflow

GET /v1/groups
GET /v1/groups/{groupId}/connections
GET /v1/connections/{connectionId}