Common Issues

Connection issues

API token is rejected or authentication fails

Double-check that you've copied the full API token from Buildkite — no extra spaces or missing characters. Also confirm the token hasn't been revoked in Personal Settings → API Access Tokens. If you generated the token a while ago and it no longer works, create a new one and update it in your Coupler.io data flow settings.

Data flow connects but returns no data

This usually means the API token doesn't have the required read scopes for the entity you selected. In Buildkite, open the token settings and verify that it includes read_builds, read_pipelines, or the relevant scope for your entity. Regenerate with the correct scopes if needed.

Missing data

Builds are missing from the export

Check your start date setting. If the start date is set too recently, older builds won't be included. Use the date picker to move the start date back further. Also verify that the builds you're looking for exist in the specific pipeline and organization you've selected.

Analytics suites entity returns empty results

Buildkite Test Analytics must be actively configured in your organization and have data ingested before this entity returns results. If you've only recently set up Test Analytics, there may not be enough data yet. Check in the Buildkite dashboard under Analytics to confirm suite data is present.

Only seeing data for some pipelines, not all

Your API token may only have access to specific pipelines or organizations. Buildkite token scopes can be restricted to particular resources. Confirm the token has org-level read access, or generate a new token with broader permissions.

Permission errors

403 Forbidden error when pulling certain entities

This means your API token doesn't have permission to access that resource. Cluster tokens, access token details, and some org-level entities require elevated permissions. Review the required scopes for the entity in Buildkite's API documentation and update your token accordingly.

Organization-level entities like Organizations clusters tokens may require a token with admin-level scopes. Be careful when sharing data flows that include these entities.

Data discrepancies

Build counts in Coupler.io don't match the Buildkite dashboard

The Buildkite dashboard may show builds that are still running or in a scheduled state at the time of your export. Coupler.io captures a point-in-time snapshot — builds that started after your data flow ran won't appear until the next run. Also check that your start date captures the same time range you're comparing against in the dashboard.

Build duration looks incorrect

Build duration is derived from started_at and finished_at timestamps. If a build was blocked or waited in a queue before running, the wall-clock time will differ from actual execution time. Use started_at rather than created_at as the start point for duration calculations.

Rate limits

Data flow fails with a rate limit error

Buildkite enforces API rate limits per token. If you're running multiple data flows using the same API token and hitting limits, consider spreading out your scheduled runs. Alternatively, use a token associated with a service account rather than a personal user account to get a higher rate limit allowance.