Push API limits

This is for:

In this article

Request size limits
Item limits
Item permission requirements
Push API daily limits
Recommended maximum number of items per hour
Security identity requirements
Security identity daily limits
Security identity validation

The Push API enforces certain limits on request size, request frequency, on items and on security identities.

On the Settings page, under License > Details (platform-ca | platform-eu | platform-au), you can review your Coveo organization license information. To upgrade your license or subscribe to another Coveo product, contact your Coveo representative.

See Review organization settings and limits for more information on your organization settings and limits.

Request size limits

You will typically get a 413 Request Entity Too Large response if your total Push API request size exceeds:

256 MB when pushing a large file container. See Manage batches of items in a Push source and Manage batches of security identities.
6 MB when pushing a single item or security identity. See Add or update a single item in a Push source, Add or update a single security identity, and Add or update a single alias.

Item limits

You will receive a 412 DOCUMENT_LIMIT_EXCEEDED response when the Items limit has been reached.

In the Coveo Administration Console, you can review your item usage and limits on the Settings page, under License > Limits (platform-ca | platform-eu | platform-au).

See Troubleshooting Push source issues for more information.

Item permission requirements

When the Same users and groups as in your content system content security option is used, the Push API enforces strict requirements regarding the number of permissions and the validity of security identities in any request to add or update items.

Validity requirement: Each item permission must reference a valid security identity.
Permissions limit: An item can contain a maximum of 5,000 permissions.

If these requirements are not met, the Push API will return a 202 Accepted response, but the item will eventually be rejected. Check the Log Browser documentation to learn how to determine whether an item has been properly processed or not.

Push API daily limits

You’ll receive a 429 TOO_MANY_DOCUMENTS_DAILY or 429 TOO_MANY_REQUESTS response respectively if you exceed one of the following daily Push API limits:

Push API calls per day: The maximum number of requests that can be made to the Push API per day.
Items processed daily by the Push API: The maximum number of items that can be sent to the Push API per day.

In the Coveo Administration Console, you can review your Push API daily usage and limits on the Settings page, under License > Limits (platform-ca | platform-eu | platform-au).

See Troubleshooting Push source issues for more information.

Recommended maximum number of items per hour

Assuming you’re using a fairly small number of batch calls to do so, you can safely push:

A sporadic burst of batches totalizing no more than 1,000,000 items over a one-hour period.

Example

Once per month, you push about 1,000,000 items over a one-hour period.
A sustained flow of batches totalizing no more than 300,000 items per hour.

Example

Once per month, over a 24-hour period, you push about 300,000 items per hour.

Always use batch requests to push multiple items or security identities.

Remember that contractually, you must contact us to arrange performance tests on Coveo.

Note

When pushing many items over a short period of time, keep in mind that buffering will typically occur.

The index speed of a Coveo organization varies based on its typical usage. Also, the more items an index contains, the longer it takes to process new items. A typical production index can process up to 300,000 items per hour, while a typical trial index can process no more than 10,000 items per hour.

Consequently, while you technically can push bursts of up to 1,000,000 items over a one-hour period, your index will typically require at least 3 hours to process all this new information. Similarly, while you can push a sustained flow of 300,000 items per hour, there’s no guarantee that your index will be able to keep up with that pace.

Security identity requirements

The Push API enforces strict requirements regarding the number and validity of security identities and their relationships in any request to add or update security identities.

Validity requirement: Every security identity, including those referenced in relationship definitions, must be valid.
Relationship limit: A single security identity cannot have more than 100,000 relationships.

If these requirements aren’t met, the API returns a 202 Accepted response, but the payload isn’t processed.

Security identity daily limits

The Push API calls per day limit is the maximum number of requests that can be made to the Push API per day. You’ll receive a 429 TOO_MANY_REQUESTS response if you exceed this limit.

The Security identity relationships processed daily by the Push API limit is the maximum number of identity relationships that the Push API will process per day. The total number of relationships associated with an identity is defined as the sum of all members, aliases, and granted identities appearing in the body of a request to add or update security identities or security identity aliases. Specifically, the total number of relationships is computed as follows:

When the request body implements the IdentityBody model, the total number of relationships is the sum of its number of members and wellKnowns.
When the request body implements the MappedIdentityBody model, the total number of relationships is the sum of its number of mappings and wellKnowns.

Every time you push an identity, even if it remains the same, the number of relationships it defines contributes to the daily count.

The Security identity relationships processed daily by the Push API limit is defined in the Limits (platform-ca | platform-eu | platform-au) page, and you’ll receive a 429 TOO_MANY_RELATIONSHIPS_DAILY response if you exceed it.

You shouldn’t be able to reach this limit in a properly configured Coveo implementation. If you do manage to reach the limit, you won’t be able to push any more relationships until your daily count resets, which may cause permission mismatches on items.

Example: Computing the number of relationships of an identity

Consider the following request body:

[
  {
    "identity": {
      "name": "Group_A",
      "type": "GROUP",
    },
    "members": [
      {
        "name": "Group_B",
        "type": "GROUP",
      }
    ],
    "wellKnowns": [
      {
        "name": "Company",
        "type": "GROUP",
      }
    ]
  },
  {
    "identity": {
      "name": "Group_B",
      "type": "GROUP",
    },
    "members": [
      {
        "name": "user1@example.com",
        "type": "User",
      },
      {
        "name": "user2@example.com",
        "type": "User",
      }
    ],
    "wellKnowns": []
  }
]

The definition of Group_A in the above request includes one member and one wellknown. Group_A therefore includes two security identity relationships.

The definition of Group_B includes two members and no wellknowns. Group_B therefore includes two security identity relationships.

Therefore, the above request pushes four security identity relationships in total.

Security identity validation

The Push API validates and rejects invalid security identities. For an identity to be valid, it must meet the following criteria:

Identity name value:
- Must be between 1 and 250 characters long
- Must not start or end with a blank character
- Must not contain control characters (for example, tabs or new line characters)
Identity aditionalInfo keys:
- Must be at least 1 character long
- Must not start or end with a blank character
- Must not contain control characters (for example, tabs or new line characters)
Total identity size: The total size of a security identity is defined as the sum of the characters in its name value and the combined number of characters used by all keys and values in the additionalInfo section. The total identity size must not exceed 500 characters.

Example: Computing the total identity size

Consider the following request body:

[
  {
    "identity": {
      "name": "User1",
      "type": "USER",
      "additionalInfo": {
      }
    },
    "members": [],
    "wellKnowns": []
  },
  {
    "identity": {
      "name": "Group1",
      "type": "GROUP",
      "additionalInfo": {
         "key": "value",
         "another_key": "another_value"
      }
    },
    "members": [],
    "wellKnowns": []
  }
]

The total size of the User1 identity is five, because its name value contains five characters and its additionalInfo section is empty.

The total size of the Group1 identity is 38, because its name value contains six characters and its additionalInfo section contains 32 characters (that is, 3+5+11+13).