> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregation

> How background and foreground aggregation work in the Platform API, and the limits on how often you can aggregate a member.

Aggregation gathers a member's data from its financial institution. MX aggregates members automatically in the background, and you can also start aggregation yourself while the end user is present.

## Aggregation timing and status fields

The member fields that report aggregation timing and status depend on the API version:

| Information | v20111101 and v20250224 | v20260929 |
| :- | :- | :- |
| When aggregation was last attempted | `aggregated_at` on the member | `products.last_attempted_at` on the member status |
| When aggregation last succeeded | `successfully_aggregated_at` on the member | `products.last_updated_at` on the member status |
| Connection status | `connection_status` on the member | `status` on the member status |

This page uses "last successful aggregation" and "connection status" to refer to these fields in every version.

## Background aggregation

MX automatically aggregates each member about every 24 hours, keeping end user data current. If a member's last successful aggregation was within the last 24 hours, you can skip foreground aggregation and read the member's account and transaction data directly.

Background aggregation runs only when:

* The institution supports background aggregation. Most do.
* The member hasn't been aggregated in the last 20 hours.
* The member's connection status is `CONNECTED`, `UPDATED`, or `CREATED`.

To turn off background aggregation:

* **For all members:** Contact MX.
* **For one member:** Set `background_aggregation_is_disabled` to `true` when you create or update the member.
* **In the Connect Widget:** Set the `disable_background_agg` widget option.

Background aggregation is off by default for members created for account verification. To turn it on, set `disable_background_agg` to `false`. This affects new members only.

MX may pause background aggregation for a member after several failed attempts in a row. Foreground aggregation is still available for those members.

## Foreground aggregation

Start foreground aggregation when the end user is present. The end user must be available to respond to multi-factor authentication (MFA) challenges, update credentials, accept terms, or respond to other prompts from the institution.

Aggregation isn't available for disabled users. Re-enable the user before you aggregate.

## Aggregation limits

### Standard aggregation throttling

A standard aggregation brings in a member's latest account and transaction data. Background aggregation is a standard aggregation, and you start one yourself with Aggregate Transactions (`POST /users/{user_identifier}/members/{member_identifier}/transactions`). Other job types, such as account verification or statements, aren't standard aggregations.

After a standard aggregation, you can't start another standard aggregation for the same member until the throttle period ends. The default throttle period is three hours (10,800 seconds), but it can vary by institution. This applies to both foreground and background aggregation.

* **Throttled requests don't return an error.** The response is `202 Accepted` and includes the member's current connection status.
* **Premium jobs aren't throttled** and don't start the throttle period. Premium jobs are extended transaction history, identity verification, account verification, statements, and balance checks. You can run one right after a standard aggregation.
* **Members with credential errors aren't throttled.** This applies when the connection status is `REJECTED`, `PREVENTED`, or `UPDATED`.
* **MX Bank isn't throttled.** There's no throttling of any kind when you use the MX Bank test institution.

Balance checks are limited to 5 per member every 2 hours. Additional balance checks in that window return `429 Too Many Requests`. Test institutions are exempt.

Spread aggregation requests out by user over each three-hour window instead of aggregating your whole platform at once. While you develop your integration, watch the last successful aggregation time to see when a member was aggregated.

For request rate limits, see [Rate Limits](./rate-limits).

## Data availability

Aggregation isn't guaranteed to return every data point for a resource. Institutions don't always provide every field, so a resource may include some fields and return `null` for others. Expect this for every resource and every type of aggregation.