Common Issues

Connection issues

Authentication fails after entering my API token

Double-check that you're using a personal API token, not an OAuth token or a project token. Generate one at CircleCI → User Settings → Personal API Tokens. Make sure you copy the full token without leading or trailing spaces.

Connection succeeds but no data is returned

This usually means the authenticated user doesn't have access to the org or project you're querying. Confirm that the account associated with the API token is a member of the organization and has at least read access to the relevant projects.

Missing data

Insights metrics or Insights branches show no rows

Insights data requires that pipelines have run within the reporting window CircleCI uses on their end. If the project is new or hasn't had recent activity, insights may be empty. Also verify that the project_id parameter matches the correct project — a mismatch will silently return nothing.

Jobs entity returns no data

The Jobs entity requires a job number. If you haven't specified one, Coupler.io will attempt to auto-fetch it from Workflow jobs. Make sure the Workflow jobs entity is included and has data, or manually provide the job number from your pipeline URLs.

Historical data is missing before a certain date

CircleCI's API has retention limits on older pipeline data depending on your plan. Data beyond the retention window won't be returned regardless of the start date you set. Check your CircleCI plan's data retention policy.

Permission errors

403 Forbidden error when fetching Contexts

Context data is restricted to organization admins in many CircleCI plans. If your account is not an org admin, you'll receive a 403. Ask your CircleCI org admin to either grant elevated permissions or pull context data using their token.

Cannot access data for a specific project

Confirm that the API token belongs to a user who has been granted access to that project in CircleCI. Private projects require explicit project membership — org membership alone may not be sufficient.

Data discrepancies

Pipeline counts in Coupler.io don't match what I see in the CircleCI dashboard

The most common cause is the start date cutoff. The CircleCI dashboard may show all-time data while your Coupler.io data flow is scoped to a specific start date. Adjust the start date or check whether the dashboard is applying its own date filters.

Workflow duration looks different from what CircleCI reports

Coupler.io surfaces raw created_at and stopped_at timestamps. If you're calculating duration yourself (e.g., in a spreadsheet formula), make sure both fields are being parsed as timestamps in the same timezone. CircleCI timestamps are in UTC.

Rate limits

Sync is slow or times out on the first historical load

CircleCI rate-limits API requests. Large organizations with many pipelines will take longer on the initial sync because Coupler.io needs to paginate through all historical records from your start date. Set a more recent start date to reduce the volume of data on the first run, then adjust once everything is working.