Skip to main content

Submit analytics events​

Submit 1 to 100 analytics events in one request. The API handles each batch as a single unit and never partially accepts a batch. A 202 Accepted response means every event passed validation and received a durable queue acknowledgement; accepted therefore matches the number of submitted events. A 422 Unprocessable Entity response means the entire batch was rejected before publication. Its message identifies the invalid value using an events[index].field path so you can correct and resubmit the batch.

version tells downstream systems which event structure they are receiving. For example, version 1 uses verse_number, while version 2 uses verse_key. Keep the same version when adding optional properties; increase it for incompatible structure changes.

Delivery is at least once. If the API returns 503 Service Unavailable, retry the batch with the same event IDs. A failed request may have published some events before the failure, and stable event IDs allow downstream processing to identify duplicates.

Do not include client_id, app_id, or environment identity in the request body. The API associates events with the authenticated client ID. When an event belongs to a signed-in Quran Foundation user, set user_id to the QF user ID associated with that user's Quran Foundation OAuth identity. Omit it for guests or unknown users, and do not send an application-local user ID. See the request schema for property and identifier limits.

Request Body required

A batch containing between 1 and 100 analytics events.

    events object[] required

    Possible values: >= 1, <= 100

    Events to accept as one batch. Send between 1 and 100 events.

  • Array [
    • action_id stringnull

    Possible values: <= 128 characters

    An optional identifier that links this event to a specific user action or interaction.

    anonymous_id stringnull

    Possible values: <= 128 characters

    An application-generated identifier for a person who is not signed in. Omit or send null when the event is not associated with an anonymous visitor.

    event_id string required

    Possible values: non-empty and <= 128 characters

    A stable identifier generated by the caller for this event.

    Reuse the same value when retrying an event. Together with the authenticated client ID, this identifies duplicates during downstream processing.

    name string required

    Possible values: non-empty and <= 128 characters

    A namespaced event name containing letters, numbers, ., _, :, or -.

    occurred_at date-time required

    When the event happened, as an RFC 3339 timestamp.

    The timestamp cannot be more than 5 minutes in the future or more than 366 days old.

    properties object

    Event-specific JSON data.

    The object may contain at most 50 keys across all nesting levels, may be nested up to 6 levels, may contain strings up to 4,096 characters, and must serialize to at most 16 KiB. Do not include credentials, access tokens, or other secrets.

    session_id stringnull

    Possible values: <= 128 characters

    An application-generated identifier that groups events from one usage session. Omit or send null when no session is available.

    user_id stringnull

    Possible values: non-empty and <= 128 characters

    Optional Quran Foundation user ID for the signed-in person associated with this event.

    Include this field only when your application has identified the person through Quran Foundation OAuth, and use the QF user ID associated with that identity. Omit it or send null for guests or unknown users. Do not send an application-local user ID.

    version int32 required

    Possible values: >= 1

    Tells downstream systems which structure this event uses. This is not the Analytics API version or your application version. Start at 1. For example, version 1 uses verse_number, while version 2 uses verse_key. Keep the same version when adding an optional property; increase it when renaming, removing, or changing the type of a property.

  • ]
Responses

The complete batch was validated and durably accepted for asynchronous processing.

Schema
    accepted integer required

    Number of events accepted from the request. Because batches are never partially accepted, this always matches the number of submitted events in a 202 Accepted response.

    batch_id uuid required

    Server-generated identifier shared by all events in this request.

Loading...