API clients / Methods / Insights

Mar 27, 2025

Send events

This is documentation for v3 of the PHP API clients, which is not the latest version. To see the documentation for the latest version, see PHP v4.

This is documentation for v2 of the Ruby API clients, which is not the latest version. To see the documentation for the latest version, see Ruby v3.

This is documentation for v4 of the JavaScript API clients, which is not the latest version. To see the documentation for the latest version, see JavaScript v5.

This is documentation for v3 of the Python API clients, which is not the latest version. To see the documentation for the latest version, see Python v4.

This is documentation for v8 of the Swift API clients, which is not the latest version. To see the documentation for the latest version, see Swift v9.

This is documentation for v2 of the Kotlin API clients, which is not the latest version. To see the documentation for the latest version, see Kotlin v3.

This is documentation for v6 of the C# API clients, which is not the latest version. To see the documentation for the latest version, see C# v7.

This is documentation for v3 of the Java API clients, which is not the latest version. To see the documentation for the latest version, see Java v4.

This is documentation for v3 of the Go API clients, which is not the latest version. To see the documentation for the latest version, see Go v4.

This is documentation for v1 of the Scala API clients, which is not the latest version. To see the documentation for the latest version, see Scala v2.

Required API Key: any key with the search ACL

Method signature

$insights->sendEvents(array events)

// Send a single event
$insights->sendEvent(array event)

insights.send_events(Array events)

# Send a single event
insights.send_event(Hash event)

aa('sendEvents', Array events, additionalParams);

insights.send_events(list events)

# Send a single event
insights.send_events(dict event)

insightsClient.sendEvents(_ events: [Event],) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// Send a single event
insightsClient.sendEvent(_ event: Event,) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

suspend fun ClientInsights.sendEvents(
  events: List<Event>,
): HttpResponse

// Send a single event
suspend fun ClientInsights.sendEvent(
  event: Event,
): HttpResponse

insights.SendEventsAsync(IEnumerable<Event> events)

// Send a single event
insights.SendEventsAsync(Event event)

insights.sendEventsAsync( List<Event> events)

// Send a single event
insights.sendEventAsync(Event event)

client.SendEvents([]Event events)

// Send a single event
client.SendEvent(Event event)

send events Seq(events events)

// Send a single event
send event (event event)

See code examples

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Send a list of events in a single request.

Sending multiple events in a batch can be useful when:

Importing historical data
Sending events from your backend,

You can include up to 1,000 events in a single request.

When you’re sending historical events, make sure to set correct timestamps for all events, or else every event will have the same timestamp.

For sending real-time events, use the dedicated methods instead:

Guides Get started with click and conversion events

Send click and conversion events with InstantSearch

Send click and conversion events with Autocomplete

API Insights API

Examples

Read the Algolia CLI documentation for more information.

The following example sends three events for the same user: one click event, one view event, and one conversion event.

For more information about initializing the Insights client aa, see Initialize the Insights client.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
$insights = Algolia\AlgoliaSearch\InsightsClient::create(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
);

$response = $insights->sendEvents(array(
    // `clickedObjectIDsAfterSearch`
    array(
        'eventType' => 'click',
        'eventName' => 'Example Clicked',
        'index' => 'YourIndexName',
        'userToken' => 'user-123456',
        'objectIDs' => array('objectID-1', 'objectID-2'),
        'timestamp' => 1747152224885,
        'queryID' => 'queryID'
    ),
    // `viewedObjectIDs`
    array(
        'eventType' => 'view',
        'eventName' => 'Example Viewed',
        'index' => 'YourIndexName',
        'userToken' => 'user-123456',
        'objectIDs' => array('objectID-1', 'objectID-2'),
        'timestamp' => 1747152224885
    ),
    // `convertedObjectIDsAfterSearch`
    array(
        'eventType' => 'conversion',
        'eventName' => 'Example Converted',
        'index' => 'YourIndexName',
         'userToken' => 'user-123456',
        'objectIDs' => array('objectID-1', 'objectID-2'),
        'timestamp' => 1747152224885,
        'queryID' => 'queryID'
    ),
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
insights = Algolia::Insights::Client.create('YourApplicationID', 'YourSearchOnlyAPIKey')

insights.send_events(
  [
    {
        eventType: 'click',
        eventName: 'Example Clicked',
        index: 'YourIndexName',
        userToken: 'user-123456',
        timestamp: 1747152224921,
        objectIDs: ['objectID-1', 'objectID-2'],
        queryID: 'queryID',
        positions: [17, 19]
      },
      {
        eventType: 'view',
        eventName: 'Example Viewed',
        index: 'YourIndexName',
        userToken: 'user-123456',
        timestamp: 1747152224921,
        objectIDs: ['objectID-1', 'objectID-2']
      },
      {
        eventType: 'conversion',
        eventName: 'Example Converted',
        index: 'YourIndexName',
        userToken: 'user-123456',
        timestamp: 1747152224921,
        objectIDs: ['objectID-1', 'objectID-2'],
        queryID: 'queryID'
      }
  ]
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// This requires the `search-insights` library version 2.9.0 or later
aa('sendEvents', [
  // `clickedObjectIDsAfterSearch`
  {
    userToken: 'anonymous-123456',
    authenticatedUserToken: 'user-123456',
    eventType: 'click',
    eventName: 'Example Clicked',
    index: 'YourIndexName',
    queryID: 'queryID',
    objectIDs: ['objectID-1', 'objectID-2'],
    positions: [17, 19],
  },
  // `viewedObjectIDs`
  {
    userToken: 'anonymous-123456',
    authenticatedUserToken: 'user-123456',
    eventType: 'view',
    eventName: 'Example Viewed',
    index: 'YourIndexName',
    objectIDs: ['objectID-1', 'objectID-2'],
  },
  // `convertedObjectIDsAfterSearch`
  {
    userToken: 'anonymous-123456',
    authenticatedUserToken: 'user-123456',
    eventType: 'conversion',
    eventSubtype: 'purchase',
    eventName: 'Example Converted',
    index: 'YourIndexName',
    objectIDs: ['objectID-1', 'objectID-2'],
    objectData: [{
      queryID: 'object1-query',
      price: '1.50',
      quantity: 2,
    }, {
      queryID: 'object2-query',
      price: '2.00',
      quantity: 1,
    }],
    value: 5.00,
    currency: 'USD',
  },
]);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
insights = InsightsClient.create(
    'YourApplicationID',
    'YourSearchOnlyAPIKey'
)

insights.send_events(
  [
    {
        "eventType": "click",
        "eventName": "Example Clicked",
        "index": "YourIndexName",
        "userToken": "user-123456",
        "timestamp": 1747152224916,
        "objectIDs": ["objectID-1", "objectID-2"],
        "queryID": "queryID",
        "positions": [17, 19]
      },
      {
        "eventType": "view",
        "eventName":"Example Viewed",
        "index": "YourIndexName",
        "userToken": "user-123456",
        "timestamp": 1747152224916,
        "objectIDs": ["objectID-1", "objectID-2"]
      },
      {
        "eventType": "conversion",
        "eventName": "Example Converted",
        "index": "YourIndexName",
        "userToken": "user-123456",
        "timestamp": 1747152224916,
        "objectIDs": ["objectID-1", "objectID-2"]
        "queryID": "queryID"
      }
  ]
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
let insightsClient = InsightsClient(appID: "YourApplicationID", apiKey: "YourSearchOnlyAPIKey")

// `clickedObjectIDsAfterSearch`
let eventClick: InsightsEvent = .click(
  eventName: "Example Clicked",
  indexName: "YourIndexName",
  userToken: "user-123456",
  queryID: "queryID",
  objectIDsWithPositions: [
    ("objectID-1", 17),
    ("objectID-2", 19),
  ])

// `viewedObjectIDs`
let eventView: InsightsEvent = .view(
  eventName: "Example Viewed",
  indexName: "YourIndexName",
  userToken: "user-123456",
  objectIDs: [
    "objectID-1",
    "objectID-2",
  ])

// `convertedObjectIDsAfterSearch`
let eventConversion: InsightsEvent = .conversion(
  eventName: "Example Converted",
  indexName: "YourIndexName",
  userToken: "user-123456",
  queryID: "queryID",
  objectIDs: [
    "objectID-1",
    "objectID-2",
  ])

let events = [eventClick, eventView, eventConversion]

insightsClient.sendEvents(events) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
val insights = ClientInsights(
  applicationID = ApplicationID("YourApplicationID"),
  apiKey = APIKey("YourSearchOnlyAPIKey")
)

// `clickedObjectIDsAfterSearch`
val eventClick = InsightsEvent.Click(
  eventName = EventName("Example Clicked"),
  indexName = IndexName("YourIndexName"),
  userToken = UserToken("user-123456"),
  timestamp = 1747152224847L,
  queryID = QueryID("queryID"),
  resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID-1"), ObjectID("objectID-2"))),
  positions = listOf(17, 19)
)

// `viewedObjectIDs`
val eventView = InsightsEvent.View(
  eventName = EventName("Example Viewed"),
  indexName = IndexName("YourIndexName"),
  userToken = UserToken("user-123456"),
  timestamp = 1747152224847L,
  resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID-1"), ObjectID("objectID-2"))),
)

// `convertedObjectIDsAfterSearch`
val eventConversion = InsightsEvent.Conversion(
  eventName = EventName("Example Converted"),
  indexName = IndexName("YourIndexName"),
  userToken = UserToken("user-123456"),
  timestamp = 1747152224847L,
  queryID = QueryID("queryID"),
  resources = InsightsEvent.Resources.ObjectIDs(listOf(ObjectID("objectID-1"), ObjectID("objectID-2"))),
)

insights.sendEvents(events = listOf(eventClick, eventView, eventConversion))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
var insights = new InsightsClient(
  "YourApplicationID",
  "YourSearchOnlyAPIKey"
);

var events = new List<InsightsEvent>(){
  // `clickedObjectIDsAfterSearch`
  new InsightsEvent(
    EventType = "click",
    UserToken = "user-123456",
    EventName = "Example Clicked",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    Positions = new List<uint> { 17, 19 },
    QueryID = "queryID",
    Timestamp = 1747152224825;
  ),
  // `viewedObjectIDs`
  new InsightsEvent(
    EventType = "view",
    UserToken = "user-123456",
    EventName = "Example Viewed",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    Timestamp = 1747152224826;
  ),
  // `convertedObjectIDsAfterSearch`
  new InsightsEvent(
    EventType = "conversion",
    UserToken = "user-123456",
    EventName = "Example Converted",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    QueryID = "queryID",
  )
};

insights.sendEventsAsync(events);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
InsightsClient insights = DefaultInsightsClient.create(
  "YourApplicationID",
  "YourSearchOnlyAPIKey"
);

// `clickedObjectIDsAfterSearch`
InsightsEvent eventClick =
  new InsightsEvent()
  .setEventType("click")
  .setUserToken("user-123456")
  .setEventName("Example Clicked")
  .setIndex("YourIndexName")
  .setObjectIDs(Arrays.asList("objectID-1", "objectID-2"))
  .setPositions(Arrays.asList(17L, 19L))
  .setQueryID("queryID")
  .setTimestamp(1747152224835L);

// `viewedObjectIDs`
InsightsEvent eventView =
  new InsightsEvent()
  .setEventType("view")
  .setUserToken("user-123456")
  .setEventName("Example Viewed")
  .setIndex("YourIndexName")
  .setObjectIDs(Arrays.asList("objectID-1", "objectID-2"))
  .setTimestamp(1747152224835L);

// `convertedObjectIDsAfterSearch`
InsightsEvent eventConversion =
  new InsightsEvent()
  .setEventType("conversion")
  .setUserToken("user-123456")
  .setEventName("Example Converted")
  .setIndex("YourIndexName")
  .setObjectIDs(Arrays.asList("objectID-1", "objectID-2"))
  .setQueryID("queryID");

List < InsightsEvent > events = Arrays.asList(eventClick, eventView, eventConversion);
insights.sendEventsAsync(events);
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
client := insights.NewClient("YourApplicationID", "YourAPIKey")

events := []insights.Event{
  // `clickedObjectIDsAfterSearch`
  {
    EventType: "click",
    EventName: "Example Clicked",
    Index: "YourIndexName",
    UserToken: "user-123456",
    Timestamp: time.Unix(1747152224830, 0),
    ObjectIDs: []string{"objectID-1", "objectID-2"},
    Positions: []int{17, 19},
    QueryID: "queryID"
  },
  // `viewedObjectIDs`
  {
    EventType: "view",
    EventName: "Example Viewed",
    Index: "YourIndexName",
    UserToken: "user-123456",
    Timestamp: time.Unix(1747152224830, 0),
    ObjectIDs: []string{"objectID-1", "objectID-2"}
  },
  // `convertedObjectIDsAfterSearch`
  {
    EventType: "conversion",
    EventName: "Example Converted",
    Index: "YourIndexName",
    UserToken: "user-123456",
    Timestamp: time.Unix(1747152224830, 0),
    ObjectIDs: []string{"objectID-1", "objectID-2"},
    QueryID: "queryID"
  },
}

res, err := client.SendEvents(events)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
client.execute {
  val eventClick = InsightsEvent(
    eventType = "click",
    eventName = "Example Clicked",
    index = "YourIndexName",
    userToken = "user-123456",
    objectIDs = Some(Seq("objectID-1", "objectID-2")),
    positions = Some(Seq(17, 19)),
    queryID = Some("queryID"),
    timestamp = Some(1747152224927L)
  )

  val eventView = InsightsEvent(
    eventType = "view",
    eventName = "Example Viewed",
    index = "YourIndexName",
    userToken = "user-123456",
    objectIDs = Some(Seq("objectID-1", "objectID-2")),
    timestamp = Some(1747152224927L)
  )

  val eventConversion = InsightsEvent(
    eventType = "conversion",
    eventName = "Example Converted",
    index = "YourIndexName",
    userToken = "user-123456",
    objectIDs = Some(Seq("objectID-1", "objectID-2")),
    queryID = Some("queryID"),
    timestamp = Some(1747152224927L)
  )

  send events Seq(eventClick, eventView, eventConversion)
}

Parameters


            events

type: array

items: event

Required

An array of event objects


            additionalParams

since: v2.4.0

type: { headers?: Record<string, string>, inferQueryID?: boolean }

default: undefined

Optional

Additional parameters to forward to the Insights library. This lets multiple search clients use different credentials for each request, or to infer the queryID for conversion events from earlier click events.

Copy
aa(
  'sendEvents',
  [
    // …
  ],
  {
    headers: {
      'X-Algolia-Application-Id': 'YourApplicationID',
      'X-Algolia-API-Key': 'YourSearchOnlyAPIKey',
    },
    inferQueryID: true,
  }
);

events ➔ event

`eventType`	type: click \| conversion \| view Required Type of the event, either `click`, `conversion`, or `view`. See also: Event types
`eventSubtype`	type: addToCart \| purchase Optional This parameter is only supported in the following languages: PHP, Ruby, JavaScript, Python, and Go. Subtype of the event. For `conversion` events either `addToCart`, or `purchase`. For all other events it should be omitted. Used to enable Algolia to provide more detailed analytics reports.
`eventName`	type: string pattern: `[\x20-\x7E]{1,64}` Required Name of the specific event. Format: 1-64 ASCII characters, except control characters. To maximize the impact of your events, use consistent event names and consistent formatting—for example, “Product Added To Cart” (always in title case). For example, you can adopt Segment’s object-action framework.
`index`	type: string Required Name of the Algolia index. Format: same as the index name used by the search engine.
`userToken`	type: string pattern: `[A-Za-z0-9_=+/-]{1,129}` Required Anonymous user identifier. See also: User Token
`authenticatedUserToken`	type: string pattern: `[A-Za-z0-9_=+/-]{1,129}` Optional Pseudonymous identifier for authenticated users. Never include personally identifiable information in user tokens. See also: User Token
`timestamp`	type: int64 default: now() Optional Time of the event in milliseconds in Unix epoch time. By default, the Insights API uses the time it receives an event as its timestamp. If you’re not sending events in real time—for example, if you’re doing backend search, it’s important to set correct timestamps. If you’re sending events in batches and you’re not including a timestamp, all events will have the same timestamp. All events: timestamp may be up to 4 days in the past. In addition, for events with `queryID`: timestamp must be within 1 hour of the corresponding search or browse request.
`queryID`	type: string pattern: `[a-f0-9]{32}` Optional Unique identifier for a search query. A `queryID` is required for events related to search or browse requests. If you add `clickAnalytics: true` as a search request parameter, the `queryID` is included in the API response. See also: Keep track of query IDs
`objectIDs`	type: array items: string Optional List of object identifiers for items of an Algolia index. You can include up to 20 `objectID`. A single event must not include both `objectIDs` and `filters`.
`objectData`	type: array items: ObjectData Optional This parameter is only supported in the following languages: PHP, Ruby, JavaScript, Python, and Kotlin. Extra information about the records involved in the event—for example, to add price and quantities of purchased products. If provided, must be the same length as `objectIDs`. If you include pricing information, you must also specify the `currency` parameter.
`value`	type: number \| string Optional This parameter is only supported in the following languages: PHP, Ruby, JavaScript, and Python. The monetary value of the event, measured in `currency`. For example, the total value of a purchase. If you assign a `value`, you must also specify the `currency` parameter. Must be a decimal number with no more than 16 characters (including non-digit characters).
`currency`	type: string Optional This parameter is only supported in the following languages: PHP, Ruby, JavaScript, and Python. If you include pricing information in the `objectData` parameter or provide `value`, you must also specify the currency as ISO-4217 currency code, such as USD or EUR.
`filters`	type: array items: string pattern: `${attr}:${value}` Optional List of facet filters. You can include up to 10 filters. Format: `${attribute}:${value}`—for example, `brand:apple`. Both the `attribute` and `value` in each facet filter must be URL-encoded individually and separated by a `:`, such as, `"discount:10%25"`. A single event must not include both `objectIDs` and `filters`.
`positions`	type: array items: uint Optional Positions of the clicked objects in the search results. This property is required for click events with `queryID`. The first search result has a position of 1 (not 0). You must provide one `position` for each `objectID`. Algolia uses this parameter to calculate the average click position. The position is absolute, and not relative, to any results page. For example, if there are 10 results per page, the position of the third record of the second results page is 13. Since `page` starts at 0, you can use the following formula: `$positionOnPage + $page * hitsPerPage`. If you’re using InstantSearch, you can get the position through the `hit.__position` attribute.

ObjectData

`queryID`	type: string pattern: `[a-f0-9]{32}` Optional ID of the query that this specific record is attributable to. Used to track purchase events with multiple items originating from different searches. Objects without a query ID aren’t included in revenue analytics. For more information, see Revenue transactions. See also: Keep track of query IDs
`price`	type: number \| string Optional The price of the item. This should be the final price, inclusive of any discounts in effect. Must be a decimal number with no more than 16 characters (including non-digit characters).
`quantity`	type: number Optional The quantity of the purchased or added-to-cart item. The total value of a purchase is the sum of `quantity` multiplied by the `price` of each purchased item.
`discount`	type: number \| string Optional Absolute value of the discount in effect for this object, measured in `currency`. Must be a decimal number with no more than 16 characters (including non-digit characters).

Response

This method doesn't return a response.

Did you find this page helpful?