Pagination and tailing

This page explains how to use pagination and tailing when calling the endpoints of the manager API.

Pagination

Pagination is supported for most endpoints of the manager API. For exceptions, see Tailing an endpoint for updated records.

Set the page size

By default, manager API endpoints return pages containing 100 records. You can change this number using the per query parameter.

To set the pages size, use the following endpoint:

/manager/api/v1/agents?per=50

This sets the page size to 50 records.

Request a specific page

You can request a specific page of records using the page query parameter.

To request a specific page, use the following endpoint:

/manager/api/v1/agents?page=2

This returns the second page of records

Get all available records

By default, the manager API returns 100 records in a response page, although you can change the number of records in a page by setting the page size. For the endpoints that support pagination, the response header includes the total number of records available. If that number exceeds your page size, you need to call the API multiple times to get all of the records. The manager API doesn't explicitly indicate that there are additional records to return.

To get all available records, do the following:

  1. Call a manager API endpoint that supports pagination. For more information, see Pagination. The response header indicates how many records there are to return.

  2. Compare the number of records to return with your page size. If the number of records to return is less than your page size, all of the records have been returned. Otherwise continue to the next step.

  3. Call the endpoint again, specifying the next page of records. For more information, see Request a specific page. Repeat this step until all of you records are returned.

Tailing an endpoint for updated records

Google recommends against using pagination for the call, chat, and agent activity endpoints because we can't guarantee optimal results. Instead, we recommend tailing these endpoints for updated records. Tailing an endpoint means continuously calling it to get records that are new or updated since your last request.

Tail an endpoint

Whenever a record is modified, its timestamp is updated. You can use the timestamp to specify the records that you want to retrieve when calling the endpoint.

To tail an endpoint, follow these steps:

  1. Call the endpoint, specifying the following query parameters:

    • updated_at[from]. Specify that you want records that were updated on or after this time.

    • sort_column. Specify the field to sort the records by.

    • sort_direction. Specify the sort direction of the records in the response.

    See the following example request:

    timestamp = "2025-01-01T00:00:00Z" # UTC timestamp
curl /manager/api/v1/calls?updated_at[from]=timestamp&sort_column=updated_at&sort_direction=asc

    The API returns a response similar to the following:

      [
    {
      "id": 100,
      ...
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": 98,
      ...
      "updated_at": "2025-01-02T00:00:00Z"
    },
    {
      "id": 150,
      ...
      "updated_at": "2025-01-03T00:00:00Z"
    }
  ]

    Response objects updated on or after 2025-01-01T00:00:00Z are returned, sorted by date, in ascending order. Use the updated_at timestamp from the last object in this response for the timestamp in your next call to the endpoint. In this example, that's 2025-01-03T00:00:00Z.

  2. Call the endpoint again, using the last updated_at value from the previous response as the timestamp. See the following example request:

    timestamp = "2025-01-03T00:00:00Z" # UTC timestamp
curl /manager/api/v1/calls?updated_at[from]=timestamp&sort_column=updated_at&sort_direction=asc

  3. Repeat the previous step to continue tailing the endpoint.