Algolia Insights API

openapi: 3.2.0
info:
  title: Insights API
  summary: The Insights API lets you collect events related to your search and discovery experience
  description: "Events represent user interactions with your app or website.\nThey unlock powerful features, such as recommendations, personalization, smarter search results,\nand analytics that help you optimize your user experience.\n\n## Client libraries\n\nUse Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API.\nFor more information, see [Algolia's ecosystem](https://www.algolia.com/doc/libraries).\n\n## Base URLs\n\nThe base URLs for making requests to the Insights API are:\n\n- `https://insights.us.algolia.io`\n- `https://insights.de.algolia.io`\n- `https//insights.algolia.io` (routes requests to the closest of the above servers, based on your geographical location)\n\n**All requests must use HTTPS.**\n\n## Authentication\n\nAdd these headers to authenticate requests:\n\n- `x-algolia-application-id`. Your Algolia application ID.\n- `x-algolia-api-key`. An API key with the necessary permissions to make the request.\n  The required access control list (ACL) to make a request is listed in each endpoint's reference.\n\nYou can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).\n\n## Request format\n\nRequest bodies must be JSON objects.\n\n## Response status and errors\n\nResponse bodies are JSON objects.\nDeleting a user token returns an empty response body with rate-limiting information as headers.\n\nSuccessful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.\nError responses have a `message` property with more information.\n\nThe Insights API doesn't validate if the event parameters such as `indexName`, `objectIDs`, or `userToken`,\ncorrespond to anything in the Search API. It just checks if they're formatted correctly.\nCheck the [Events](https://dashboard.algolia.com/events/health) health section,\nwhether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking.\n\n## Version\n\nThe current version of the Insights API is version 1, indicated by the `/1/` in each endpoint's URL.\n"
  version: 1.0.0
servers:
- url: https://insights.{region}.algolia.io
  variables:
    region:
      description: The region where your Algolia application is hosted.
      enum:
      - us
      - de
      default: us
- url: https://insights.algolia.io
security:
- appId: []
  apiKey: []
tags:
- name: insights
paths:
  /{path}:
    get:
      operationId: customGet
      summary: Send requests to the Algolia REST API
      description: This method lets you send requests to the Algolia REST API.
      parameters:
      - $ref: '#/components/parameters/PathInPath'
      - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
      - insights
    post:
      operationId: customPost
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method lets you send requests to the Algolia REST API.
      parameters:
      - $ref: '#/components/parameters/PathInPath'
      - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
      - insights
    put:
      operationId: customPut
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method lets you send requests to the Algolia REST API.
      parameters:
      - $ref: '#/components/parameters/PathInPath'
      - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
      - insights
    delete:
      operationId: customDelete
      summary: Send requests to the Algolia REST API
      description: This method lets you send requests to the Algolia REST API.
      parameters:
      - $ref: '#/components/parameters/PathInPath'
      - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
      - insights
  /1/events:
    post:
      tags:
      - insights
      operationId: pushEvents
      summary: Send events
      x-acl:
      - search
      description: 'Sends a list of events to the Insights API.


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

        but the request body must be smaller than 2 MB.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: insightsEvents
              type: object
              required:
              - events
              properties:
                events:
                  type: array
                  description: 'Click and conversion events.


                    **All** events must be valid, otherwise the API returns an error.

                    '
                  minItems: 1
                  maxItems: 1000
                  items:
                    $ref: '#/components/schemas/EventsItems'
            examples:
              ClickObjectIDsAfterSearch:
                summary: Click event after search requests
                value:
                  events:
                  - eventName: Products Clicked
                    eventType: click
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - object-1
                    positions:
                    - 1
                    queryID: 7dfe2ada7bca48bdd0629649df0bee07
              ConversionObjectIDsAfterSearch:
                summary: Conversion event after search or browse requests
                value:
                  events:
                  - eventName: Articles Liked
                    eventType: conversion
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - article-1
                    queryID: 7dfe2ada7bca48bdd0629649df0bee07
              AddedToCartAfterSearch:
                summary: Add-to-cart event after search or browse requests
                value:
                  events:
                  - eventName: Products Added To Cart
                    eventType: conversion
                    eventSubtype: addToCart
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - product-1
                    objectData:
                    - price: 50
                      quantity: 1
                    currency: USD
                    queryID: 7dfe2ada7bca48bdd0629649df0bee07
              PurchasedAfterSearch:
                summary: Purchase event after search or browse requests
                value:
                  events:
                  - eventName: Products Purchased
                    eventType: conversion
                    eventSubtype: purchase
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - product-1
                    - product-2
                    objectData:
                    - price: 49.99
                      discount: 1.99
                      quantity: 1
                      queryID: 7dfe2ada7bca48bdd0629649df0bee07
                    - price: 9.99
                      discount: 0
                      quantity: 2
                      queryID: 54ed4c9d94050a25e4e5ccf5d256ca42
                    value: 69.97
                    currency: USD
              ClickObjectIDs:
                summary: Click event
                value:
                  events:
                  - eventName: Products Clicked
                    eventType: click
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - object-1
              ConversionObjectIDs:
                summary: Conversion event
                value:
                  events:
                  - eventName: Products Added To Cart
                    eventType: conversion
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - object-1
              AddedToCart:
                summary: Add-to-cart event
                value:
                  events:
                  - eventName: Products Added To Cart
                    eventType: conversion
                    eventSubtype: addToCart
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - product-1
                    objectData:
                    - price: 19.99
                      quantity: 1
                    currency: EUR
              Purchased:
                summary: Purchase event
                value:
                  events:
                  - eventName: Products Purchased
                    eventType: conversion
                    eventSubtype: purchase
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - product-1
                    - product-2
                    objectData:
                    - price: 49.99
                      quantity: 1
                    - price: 9.99
                      quantity: 2
                    currency: USD
                    value: 69.97
              ClickFilter:
                summary: Click event with filters
                value:
                  events:
                  - eventName: Category Clicked
                    eventType: click
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    filters:
                    - category:books
              ConversionFilter:
                summary: Conversion event with filters
                value:
                  events:
                  - eventName: Category Converted
                    eventType: conversion
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    filters:
                    - category:books
              ViewObjectIDs:
                summary: View event
                value:
                  events:
                  - eventName: Products Viewed
                    eventType: view
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    objectIDs:
                    - object-1
              ViewFilters:
                summary: View event with filters
                value:
                  events:
                  - eventName: Category Viewed
                    eventType: view
                    index: test-index
                    userToken: anonymous-user-1
                    authenticatedUserToken: user-1
                    filters:
                    - category:books
              InstantsearchMinimum:
                summary: Minimum instantsearch event
                description: 'Minimum valid instantsearch event for agentic analytics telemetry.

                  '
                value:
                  events:
                  - eventName: Instantsearch Telemetry
                    eventType: instantsearch
                    userToken: anonymous-user-1
              InstantsearchWithAgentID:
                summary: Instantsearch event with agentID
                description: 'Instantsearch event with agentID to correlate events within a single agent session.

                  '
                value:
                  events:
                  - eventName: Instantsearch Telemetry
                    eventType: instantsearch
                    userToken: anonymous-user-1
                    agentID: agent-session-123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                Success:
                  summary: Events successfully sent to the Insights API
                  description: Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index.
                  value:
                    status: 200
                    message: OK
        '400':
          description: Bad Request.
          content:
            text/html:
              schema:
                type: string
                title: HTML
              examples:
                BadRequest:
                  summary: Bad request
                  description: This error doesn't return a JSON object, but HTML.
                  value: 'Error: Bad Request. Your client has issued a malformed or illegal request.'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                Unauthorized:
                  summary: Invalid credentials
                  description: You need to provide your application ID using the `X-Algolia-Application-ID` header and your (search) API key with the `X-Algolia-API-Key` header.
                  value:
                    status: 401
                    message: Invalid credentials
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                NotFound:
                  summary: Unsupported operation
                  description: Check that you're using the correct URL.
                  value:
                    status: 404
                    message: Path not supported by Insights REST API. Please have a look at [https://www.algolia.com/doc/rest-api/insights/](https://www.algolia.com/doc/rest-api/insights) for the list of valid commands.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                MethodNotAllowed:
                  summary: Method not allowed
                  description: Check, that you send events with the `POST` method.
                  value:
                    status: 405
                    message: Method Not Allowed
        '413':
          description: Payload Too Large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                PayloadTooLarge:
                  summary: Request body larger than 2&nbspMB
                  value:
                    status: 413
                    message: Request Entity Too Large
        '422':
          description: Unprocessable Entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                InvalidPayload:
                  summary: Incorrect event object
                  value:
                    status: 422
                    message: Invalid payload
                NoEvents:
                  summary: No events
                  description: This can happen if you're sending an empty `events` array, or if you try to send a single event object instead of the `events` array.
                  value:
                    status: 422
                    message: No events to process
                NoEventsField:
                  summary: Missing events attribute
                  description: This can happen if you try to send an array of events directly instead of using the `events` attribute.
                  value:
                    status: 422
                    message: 'Invalid type for field : expected insights.PublicEventsBatch, got array'
                EventNameRequired:
                  summary: Missing eventName attribute
                  value:
                    status: 422
                    message: EventName is required
                WrongEventName:
                  summary: Event name too long or wrong characters
                  value:
                    status: 422
                    message: EventName must contain only visible ASCII characters, and be between 1 and 64 characters long
                EventTypeRequired:
                  summary: Missing eventType attribute
                  value:
                    status: 422
                    message: EventType is required
                WrongEventType:
                  summary: Wrong event type
                  value:
                    status: 422
                    message: EventType must be one of "click", "conversion", "view" or "instantsearch"
                IndexRequired:
                  summary: Missing index attribute
                  value:
                    status: 422
                    message: The index field is required
                UserTokenRequired:
                  summary: Missing userToken attribute
                  value:
                    status: 422
                    message: The userToken field is required
                WrongUserToken:
                  summary: Malformed user token
                  value:
                    status: 422
                    message: UserToken must contain only alphanumeric, equal, plus, slash, hyphen, or underscore characters, and be between 1 and 128 characters long
                NoObjectIDsOrFilters:
                  summary: Missing objectIDs or filters attribute
                  description: Each event must include either the `objectIDs` or `filters` attribute.
                  value:
                    status: 422
                    message: Event should specify either some ObjectIDs or some Filters
                BothDefined:
                  summary: Both objectIDs and filters attributes defined
                  value:
                    status: 422
                    message: Event should specify ObjectIDs or Filters, but not both
                PositionsOnWrongEventType:
                  summary: Wrong combination of positions and eventType attributes
                  value:
                    status: 422
                    message: Only event of type click should specify the positions attribute
                PositionsWithoutQueryID:
                  summary: Positions attribute without queryID
                  description: Click events with the `positions` attribute require the `queryID` attribute.
                  value:
                    status: 422
                    message: Event of type click with positions should specify a queryID
                WrongPositionsValue:
                  summary: Wrong value in positions array
                  description: Any value in the `positions` array must be greater than 0.
                  value:
                    status: 422
                    message: Event of type click may only have strictly positive positions
                WrongPositionsItems:
                  summary: Wrong number of items in positions array
                  description: For click events with the `queryID` and `objectIDs` attributes, you must include the `positions` attribute with the same number of items as the `objectIDs` attribute.
                  value:
                    status: 422
                    message: Event of type click should have the same number of ObjectIDs and Positions
                WrongQueryID:
                  summary: Malformed query ID
                  value:
                    status: 422
                    message: Query ID must be a search query ID (32 characters hexadecimal string)
                InvalidDataType:
                  summary: Wrong data type
                  description: This can happen if one or more attribute is a number instead of a string.
                  value:
                    status: 422
                    message: 'Invalid type for field events: expected string, got number'
                InvalidTimestamp:
                  summary: Timestamp too old
                  value:
                    status: 422
                    message: The timestamp is too far in the past
                TooManyEvents:
                  summary: Too many events
                  description: You can include up to 1,000 events in a single API request.
                  value:
                    status: 422
                    message: Cannot process more than 1000 events in a batch
  /1/usertokens/{userToken}:
    delete:
      tags:
      - insights
      operationId: deleteUserToken
      summary: Delete user token events
      description: 'Deletes all events related to the specified user token from events metrics and analytics.

        The deletion is asynchronous, and processed within 48 hours.

        To delete a personalization user profile, see `Delete a user profile` in the Personalization API.

        '
      x-acl:
      - deleteObject
      parameters:
      - name: userToken
        in: path
        description: User token for which to delete all associated events.
        required: true
        schema:
          $ref: '#/components/schemas/userToken'
      responses:
        '204':
          description: No content.
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
        '422':
          description: Unprocessable Entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
        '429':
          description: 'Too Many Requests. This operation is rate-limited. Check the `x-ratelimit-limit` and `x-ratelimit-reset` headers of the response.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
  /setClientApiKey:
    get:
      x-helper: true
      x-asynchronous-helper: false
      x-acl: []
      tags:
      - insights
      operationId: setClientApiKey
      summary: Switch the API key used to authenticate requests
      description: 'Switch the API key used to authenticate requests.

        '
      parameters:
      - in: query
        name: apiKey
        description: API key to use for subsequent requests.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content.
components:
  schemas:
    filters:
      type: array
      description: 'Applied facet filters.


        Facet filters are `facet:value` pairs.

        Facet values must be URL-encoded, such as, `discount:10%25`.

        '
      items:
        type: string
      minItems: 1
      maxItems: 20
      example:
      - brand:apple
    EventsItems:
      oneOf:
      - $ref: '#/components/schemas/ClickedObjectIDsAfterSearch'
      - $ref: '#/components/schemas/AddedToCartObjectIDsAfterSearch'
      - $ref: '#/components/schemas/PurchasedObjectIDsAfterSearch'
      - $ref: '#/components/schemas/ConvertedObjectIDsAfterSearch'
      - $ref: '#/components/schemas/ClickedObjectIDs'
      - $ref: '#/components/schemas/PurchasedObjectIDs'
      - $ref: '#/components/schemas/AddedToCartObjectIDs'
      - $ref: '#/components/schemas/ConvertedObjectIDs'
      - $ref: '#/components/schemas/ClickedFilters'
      - $ref: '#/components/schemas/ConvertedFilters'
      - $ref: '#/components/schemas/ViewedObjectIDs'
      - $ref: '#/components/schemas/ViewedFilters'
      - $ref: '#/components/schemas/Instantsearch'
    objectDataAfterSearch:
      type: object
      additionalProperties: false
      properties:
        queryID:
          type: string
          pattern: '[0-9a-f]{32}'
          minLength: 32
          maxLength: 32
          description: Unique identifier for a search query, used to track purchase events with multiple records that originate from different searches.
          example: 3e48cd0616e466948dd85abf5c3fbbe2
        price:
          $ref: '#/components/schemas/price'
        quantity:
          $ref: '#/components/schemas/quantity'
        discount:
          $ref: '#/components/schemas/discount'
    currency:
      type: string
      minLength: 3
      maxLength: 3
      pattern: ^[A-Za-z]{3}$
      description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html).
      example: EUR
    objectDataList:
      type: array
      description: 'Extra information about the records involved in a purchase or add-to-cart event.


        If specified, it must have the same length as `objectIDs`.

        '
      items:
        $ref: '#/components/schemas/objectData'
      minItems: 1
      maxItems: 20
    InstantsearchEvent:
      type: string
      enum:
      - instantsearch
    ConvertedFilters:
      type: object
      title: Converted filters
      properties:
        eventName:
          $ref: '#/components/schemas/eventName'
        eventType:
          $ref: '#/components/schemas/ConversionEvent'
        index:
          $ref: '#/components/schemas/index'
        filters:
          $ref: '#/components/schemas/filters'
        userToken:
          $ref: '#/components/schemas/userToken'
        authenticatedUserToken:
          $ref: '#/components/schemas/authenticatedUserToken'
        timestamp:
          $ref: '#/components/schemas/timestamp'
      required:
      - eventName
      - eventType
      - index
      - filters
      - userToken
      x-discriminator-fields:
      - eventType
      - filters
    objectData:
      type: object
      additionalProperties: false
      properties:
        price:
          $ref: '#/components/schemas/price'
        quantity:
          $ref: '#/components/schemas/quantity'
        discount:
          $ref: '#/components/schemas/discount'
    Instantsearch:
      type: object
      properties:
        eventName:
          $ref: '#/components/schemas/eventName'
        eventType:
          $ref: '#/components/schemas/InstantsearchEvent'
        userToken:
          $ref: '#/components/schemas/userToken'
        authenticatedUserToken:
          $ref: '#/components/schemas/authenticatedUserToken'
        timestamp:
          $ref: '#/components/schemas/timestamp'
        agentID:
          $ref: '#/components/schemas/agentID'
      required:
      - eventName
      - eventType
      - userToken
      x-discriminator-fields:
      - eventType
    ClickEvent:
      type: string
      enum:
      - click
    ConvertedObjectIDs:
      type: object
      title: Converted object IDs
      description: 'Use this event to track when users convert on items unrelated to a previous Algolia request.

        For example, if you don''t use Algolia to build your category pages, use this event.


        To track conversion events related to Algolia requests, use the "Converted object IDs after search" event.

        '
      properties:
        eventName:
          $ref: '#/components/schemas/eventName'
        eventType:
          $ref: '#/components/schemas/ConversionEvent'
        index:
          $ref: '#/components/schemas/index'
        objectIDs:
          $ref: '#/components/schemas/objectIDs'
        userToken:
          $ref: '#/components/schemas/userToken'
        authenticatedUserToken:
          $ref: '#/components/schemas/authenticatedUserToken'
        timestamp:
          $ref: '#/components/schemas/timestamp'
      required:
      - eventName
      - eventType
      - index
      - objectIDs
      - userToken
      x-discriminator-fields:
      - eventType
      - objectIDs
    userToken:
      type: string
      minLength: 1
      maxLength: 129
      pattern: '[a-zA-Z0-9_=/+-]{1,129}'
      description: 'Anonymous or pseudonymous user identifier.


        Don''t use personally identifiable information in user tokens.

        For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken).

        '
      example: test-user-1
    ConvertedObjectIDsAfterSearch:
      type: object
      title: Converted object IDs after search
      description: 'Use this event to track when users convert after a previous Algolia request.

        For example, a user clicks on an item in the search results to view the product detail page.

        Then, the user adds the item to their shopping cart.


        If you''re building your category pages with Algolia,

        you''ll also use this event.

        '
      properties:
        eventName:
          $ref: '#/components/schemas/eventName'
        eventType:
          $ref: '#/components/schemas/ConversionEvent'
        index:
          $ref: '#/components/schemas/index'
        objectIDs:
          $ref: '#/components/schemas/objectIDs'
        queryID:
          $ref: '#/components/schemas/queryID'
        userToken:
          $ref: '#/components/schemas/userToken'
        authenticatedUserToken:
          $ref: '#/components/schemas/authenticatedUserToken'
        timestamp:
          $ref: '#/components/schemas/timestamp'
      required:
      - eventName
      - eventType
      - index
      - objectIDs
      - queryID
      - userToken
      x-discriminator-fields:
      - queryID
      - eventType
    discount:
      description: Absolute value of the discount for this product, in units of `currency`.
      oneOf:
      - type: number
        format: double
        example: 20
      - type: string
        example: '20'
    ViewEvent:
      type: string
      enum:
      - view
    AddedToCartObjectIDsAfterSearch:
      type: object
      title:

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/algolia/refs/heads/main/openapi/algolia-insights-api-openapi.yml