Measure logo
REST API ReferenceSDK APIEvents

Ingest a batch of events and spans

PUT/events

Ingests a batch of events, which can be of different types and can range across multiple sessions.

Usage notes:

  • Maximum size of one request must not exceed 10 MiB. This limit includes the combination of events and blob data.
  • Each request must contain a unique UUIDv4 id, set as the header msr-req-id. If a request fails, the client must retry the same payload with the same msr-req-id to ensure idempotency.
  • Each event must contain a nanosecond precision timestamp, for example "2023-08-24T14:51:38.000000534Z".
  • Each request must not contain duplicate event ids.
  • Each request must not contain duplicate span ids.
  • Each span must contain a nanosecond precision start_time and end_time.
  • Each event must have the following mandatory attributes: attribute.installation_id, attribute.measure_sdk_version, attribute.thread_name, attribute.app_version, attribute.app_build, attribute.app_unique_id.
  • Each span must have the following mandatory fields: name, span_id, trace_id, session_id, status, start_time, end_time, attributes.installation_id, attributes.measure_sdk_version, attributes.app_version, attributes.os_version, attributes.app_unique_id.
  • At least 1 event must be present in the events array field or 1 span must be present in the spans array field. Both arrays must not be empty.
  • The request body supports both application/json and multipart/form-data requests. Multipart requests will be deprecated in future versions; multipart only exists for backwards compatibility.
  • A successful JSON request returns 200 OK with attachment upload URLs when the batch references attachments. A successful multipart request returns 202 Accepted.
  • Idempotent based on msr-req-id. Previously seen requests matching by msr-req-id won't be re-processed; JSON requests receive the attachment upload info again so the client can proceed to upload attachments if any.

A success response implies the server has accepted the request, but it may choose to not process and discard some events depending on various conditions.

Authorization

measureApiKey
AuthorizationBearer <token>

Measure API key for the app, sent as Authorization: Bearer <api-key>. The app is determined from the API key.

In: header

Header Parameters

msr-req-id*string

Unique UUIDv4 id for this request. If a request fails, retry the same payload with the same msr-req-id to ensure idempotency.

Formatuuid

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Batch of events and spans. At least one event or one span must be present.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/events" \  -H "msr-req-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "id": "576aa557-2580-4bb6-9941-ba90df6c3c0e",        "session_id": "9321a0be-906e-436b-91af-b47fb2e81cde",        "user_triggered": false,        "timestamp": "2025-10-07T12:13:01.51700000Z",        "type": "gesture_click",        "gesture_click": {          "target": "androidx.compose.ui.platform.AndroidComposeView",          "target_id": "item_0",          "width": 1080,          "height": 242,          "x": 619.959,          "y": 195.93066,          "touch_down_time": 75761066,          "touch_up_time": 75761126        },        "attachments": [          {            "id": "42306fd7-cb17-4fa4-88dd-b40ce1ce34c4",            "type": "layout_snapshot",            "name": "snapshot.svg"          }        ],        "attribute": {          "thread_name": "main",          "user_id": null,          "device_name": "emu64a16k",          "device_model": "sdk_gphone16k_arm64",          "device_manufacturer": "Google",          "device_type": "phone",          "device_is_foldable": false,          "device_is_physical": false,          "device_density_dpi": 440,          "device_width_px": 1080,          "device_height_px": 2220,          "device_density": 2.75,          "device_locale": "en-US",          "os_name": "android",          "os_version": "36",          "os_page_size": 16,          "app_version": "0.13.0-SNAPSHOT.debug",          "app_build": "29330652",          "app_unique_id": "sh.measure.sample",          "measure_sdk_version": "0.13.0-SNAPSHOT",          "installation_id": "4059d23f-34ce-4d2c-a015-bd8da0b101ae",          "network_type": "wifi",          "network_generation": "unknown",          "network_provider": "unknown",          "device_low_power_mode": false,          "device_thermal_throttling_enabled": false        },        "user_defined_attribute": null      }    ],    "spans": [      {        "name": "activity.onCreate",        "trace_id": "d71f3d909689859469a7d9b38e605d56",        "span_id": "9f1890db9aedb305",        "parent_id": null,        "session_id": "a2768feb-59cd-433f-bf00-d36ab297eddb",        "start_time": "2024-11-18T14:14:40.54500000Z",        "end_time": "2024-11-18T14:14:40.62000000Z",        "duration": 75,        "status": 0,        "attributes": {          "thread_name": "main",          "user_id": null,          "device_name": "emu64a16k",          "device_model": "sdk_gphone16k_arm64",          "device_manufacturer": "Google",          "device_locale": "en-US",          "os_name": "android",          "os_version": "35",          "app_version": "0.9.0-SNAPSHOT.debug",          "app_build": "900",          "app_unique_id": "sh.measure.sample",          "measure_sdk_version": "0.9.0-SNAPSHOT",          "installation_id": "2ee2d03e-ed76-43e7-8d63-9e146f1df618",          "network_type": "wifi",          "network_generation": "unknown",          "network_provider": "unknown"        },        "checkpoints": []      }    ]  }'

{  "attachments": [    {      "id": "42306fd7-cb17-4fa4-88dd-b40ce1ce34c4",      "type": "layout_snapshot",      "filename": "snapshot.svg",      "upload_url": "http://localhost:8080/proxy/attachments?payload=http%3A%2F%2Fminio%3A9000%2Fmsr-attachments-sandbox%2F42306fd7-cb17-4fa4-88dd-b40ce1ce34c4.svg%3FX-Amz-Algorithm%3DAWS4-HMAC-SHA256%26X-Amz-Expires%3D604800%26x-id%3DPutObject",      "expires_at": "2025-10-15T10:14:12.870600803Z",      "headers": {        "x-amz-meta-original_file_name": "snapshot.svg"      }    }  ]}

{  "ok": "accepted"}

{  "error": "failed to parse event request payload"}
{  "error": "invalid api key"}
{  "error": "ingestion blocked: plan limit reached"}
{  "error": "no app found for this api key"}
Empty
{  "error": "string"}
Empty

Think this page can be better?

Open an issue

Fetch the SDK configuration GET

Previous Page

Fetch an app's alerts GET

Next Page