Audiences API

The Audiences API enables our Brand partners to programmatically access their Audience metadata and modify the contents of their Audiences, which allows tighter integration with Button’s targeting systems, faster reactions to changes in user behavior, and support for higher-scale workloads than CSV-based audience workflows.

Rate limiting

The Button Audiences API is rate-limited on a per-organization basis in order to protect the quality of service the API provides to all of our partners. Specific request rate ceilings aren’t published as part of our API documentation, as they may change over time — if you feel your workload exceeds the default limit, please reach out to your Button representative.

You can see your usage against your organization’s limit by reading the values of the X-Button-Limit-Remaining and X-Button-Limit-Reset-Seconds headers present in each HTTP response, which represent how many more requests you can make and how long until your limit resets to the maximum. If you make too many requests, you’ll receive HTTP 429 Too Many Requests from the API and the data from your rejected requests will not be processed by Button.

We recommend you proactively pay attention to your limits and pace the work you’re doing in your application accordingly, rather than reactively handling HTTP 429 response codes.

External IDs

Throughout this document, you’ll notice that we support addressing audiences by external_id instead of their Button-generated id.

If you’re sending audiences to Button that already have unique identifiers in your system, we recommend you take advantage of our external_id support, so that you don’t need to keep track of our identifiers for your audiences.

Check out our Audiences API reference for more details.


© 2021 Button, Inc — For partner use only.