Look up request processing status

Use this endpoint to check whether Braze has finished processing a group of asynchronous /users/track endpoint requests.

important

This endpoint is in beta. If you’re interested in participating in the beta, contact your Braze account manager.

A successful response from /users/track means Braze received your request and queued it for processing. To confirm that processing has finished, include the same group_id in each related /users/track request, then call this endpoint with that group_id. When the group’s status is completed, you can safely take actions that depend on that data, such as triggering a Canvas or launching a campaign.

For the full workflow, group ID requirements, limits, and retention, see Track request processing status.

Prerequisites

To use this endpoint, you’ll need an API key with the users.track.status permission. The users.track permission doesn’t include access to this endpoint.

Any API key in the workspace with the users.track.status permission can look up any group in that workspace, regardless of which API key sent the /users/track requests.

Rate limit

Braze applies a rate limit of 1,500 requests per minute per workspace to this endpoint, as documented in API rate limits. This limit is separate from the /users/track rate limit.

Successful responses include the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can track how much of your current window remains.

Query parameters

Example request

1
2

curl --location --request GET 'https://rest.iad-01.braze.com/users/track/status?group_id=loyalty_backfill_2026-09-23' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'

Response

1
2
3
4
5
6
7
8
9
10
11
12

{
  "results": [
    {
      "group_id": (string) the group ID from your request,
      "status": (string) the processing status of the group, either "processing" or "completed",
      "received": (integer) the number of /users/track requests Braze accepted for this group,
      "done": (integer) the number of accepted requests Braze has finished processing,
      "processing": (integer) the number of accepted requests Braze is still processing,
      "final_completion_time": (string or null) when the last request in the group finished processing, in ISO 8601 format (UTC). This is null until the status is "completed".
    }
  ]
}

The results array contains one object when Braze finds the group. It’s empty when the group doesn’t exist in the workspace or its 24-hour retention period has ended. Braze returns an empty results array for both cases, so an empty array doesn’t tell you whether a group ever existed.

Response parameters

A completed status means Braze finished processing every request in the group, including requests where Braze rejected some objects. This endpoint reports request counts only and doesn’t report results for individual attributes, events, or purchases. To find rejected objects, check the errors array in each /users/track response.

Example responses

Group still processing

1
2
3
4
5
6
7
8
9
10
11
12

{
  "results": [
    {
      "group_id": "loyalty_backfill_2026-09-23",
      "status": "processing",
      "received": 4,
      "done": 3,
      "processing": 1,
      "final_completion_time": null
    }
  ]
}

Group completed

1
2
3
4
5
6
7
8
9
10
11
12

{
  "results": [
    {
      "group_id": "loyalty_backfill_2026-09-23",
      "status": "completed",
      "received": 4,
      "done": 4,
      "processing": 0,
      "final_completion_time": "2026-09-23T18:58:57.123Z"
    }
  ]
}

Group not found or expired

1
2
3

{
  "results": []
}

Troubleshooting

The following table lists errors this endpoint can return and how to resolve them.

For other status codes and error messages, see Fatal errors & responses.