Track Banner analytics events

Important:

This page is in beta. Features and documentation for the Device Messaging API are subject to change.

Use this endpoint to record impression and click events for Banners.

Braze validates each event separately. When a request contains both valid and invalid events, Braze processes the valid events and returns details about skipped events in the errors array. If no events are valid, Braze returns a 400 status code.

Prerequisites

To use this endpoint, you need the following:

• A workspace with Banners enabled
• A client-side REST API key with the banners.track permission
• The REST endpoint for your Braze instance
• A Banner id returned by the Retrieve Banners for a user endpoint

Include the client-side REST API key in the Authorization header as a bearer token.

Rate limit

Rate limits apply per workspace. If you exceed the rate limit, Braze returns a 429 status code. When available, use the X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Retry-After response headers to monitor your usage and determine when to retry.

For more information, see Device Messaging API rate limits.

Request body

1
2
3
4
5
6
7
8
9
10
11
12
{
  "external_user_id": "{EXTERNAL_USER_ID}",
  "app_id": "{APP_API_IDENTIFIER}",
  "app_version": "1.0.0",
  "events": [
    {
      "id": "{BANNER_ID}",
      "event_type": "impression",
      "timestamp": "2026-04-09T12:00:00Z"
    }
  ]
}

Request parameters

Example request

Replace YOUR_REST_API_URL with the REST endpoint for your Braze instance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl --location --request POST '{YOUR_REST_API_URL}/v1/device-messaging/banners/track' \
--header 'Authorization: Bearer {YOUR_CLIENT_SIDE_REST_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "external_user_id": "user_abc123",
  "app_id": "26a39c72-e647-4766-b62e-4521fa2dae59",
  "app_version": "1.0.0",
  "events": [
    {
      "id": "bnr_01HZ3K2QFGH9XVNJ4W8PCRMT5E",
      "event_type": "impression",
      "timestamp": "2026-04-09T12:00:00Z"
    },
    {
      "id": "bnr_01HZ3K2QFGH9XVNJ4W8PCRMT5E",
      "event_type": "click",
      "timestamp": "2026-04-09T12:00:05Z"
    }
  ]
}'

Response parameters

Example responses

All events processed

When Braze accepts all events, it returns a 202 status code.

1
2
3
4
{
  "events_processed": 2,
  "message": "success"
}

Some events skipped

Braze also returns a 202 status code when it accepts at least one valid event. The response identifies any skipped events.

1
2
3
4
5
6
7
8
9
10
{
  "events_processed": 2,
  "message": "success",
  "errors": [
    {
      "type": "Invalid event_type. Valid types are: impression, click.",
      "index": 2
    }
  ]
}

No valid events

If Braze can’t process any events, it returns a 400 status code.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "message": "No valid events provided.",
  "errors": [
    {
      "type": "Invalid event_type. Valid types are: impression, click.",
      "index": 0
    },
    {
      "type": "'timestamp' is required",
      "index": 1
    }
  ]
}

Status codes

For more information, see Device Messaging API error handling and retries.