Best Practices

Recommended setup

Use a dedicated service account token

Avoid using a personal developer token in production data flows. Create a dedicated Bugsnag user (e.g., a bot account) with the minimum required permissions, and use its Personal Auth Token. This way, your data flows won't break if a team member leaves.

Start with Errors before Events

The Errors entity is lighter and faster to export than Events. Use Errors for dashboards and trend reports. Only pull Events when you need granular, per-occurrence details — and always set a narrow start date when you do.

Split large projects into separate data flows

If you have multiple high-traffic projects, create one data flow per project rather than pulling all data in one go. This keeps exports fast and makes it easier to isolate issues if something breaks.

Data refresh and scheduling

Match refresh frequency to error volume

For production apps with active users, daily or hourly refreshes on the Errors entity give you timely stability data. For release tracking, refreshing after each deploy is more useful than a fixed schedule.

Use a rolling start date for ongoing exports

Set your start date to a fixed lookback window (e.g., the last 30 or 90 days) rather than your project's launch date. This keeps exports fast and prevents you from reprocessing historical data that hasn't changed.

Performance optimization

Use Pivots for aggregate analysis

If you want error breakdowns by OS, browser, or app version, pull the Pivots entity instead of processing raw Events. Bugsnag pre-aggregates this data, so your export will be much smaller and faster.

Join Errors and Releases in Coupler.io

Instead of pulling a combined dataset from Bugsnag, export Errors and Releases as separate entities and use Coupler.io's Join transformation to link them by app version. This gives you cleaner, more maintainable data flows.

Common pitfalls

Don't pull the full Events history for a high-traffic project in a single run — this will almost certainly hit Bugsnag's API rate limits. Always set a start date and test with a short window first.

Do

• Use the Errors entity for dashboards and trend reporting

• Set a meaningful start date for every data flow

• Use Append to combine error data from multiple projects

• Test with a manual run before scheduling

Don't

• Pull raw Events without a start date on active projects

• Use your personal token in shared or automated data flows

• Confuse the project API key (for SDKs) with the Personal Auth Token (for the API)

• Ignore 403 errors — they usually mean your token lacks org-level permissions