This page explains how to use pagination and tailing when calling the endpoints
of the [manager API](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api).

## Pagination

Pagination is supported for most endpoints of the manager API. For exceptions,
see [Tailing an endpoint for updated records](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-pagination-tailing#tailing-endpoint).

### Set the page size

By default, manager API endpoints return pages containing 100 records. You can
change this number using the `per` query parameter, up to a maximum of 100. A
larger value is reduced to 100.

To set the page 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](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-pagination-tailing#set-page-size). For the endpoints that support [pagination](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-pagination-tailing#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. For endpoints that support pagination, the response
includes a `Link` header following RFC 5988. A `rel="next"` link is present
whenever more records are available, and a `rel="last"` link gives the number
of the final page. The response also includes `Total` and `Per-Page` headers.

To get all available records, do the following:

1. Call a manager API endpoint that supports pagination. For more information,
   see [Pagination](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-pagination-tailing#pagination). The response header indicates how many
   records there are to return.

2. Compare the number of records to return with your [page
   size](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-pagination-tailing#set-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](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-pagination-tailing#request-a-specific-page). Repeat
   this step until all of you records are returned.

## Tail an endpoint for updated records

Google recommends against using pagination for the [call](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-call), [chat](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-chat),
and [agent activity](https://docs.cloud.google.com/contact-center/ccai-platform/docs/manager-api-agent-activity) API endpoints because we can't guarantee
optimal results. Instead, we recommend tailing these API endpoints for updated
records. Tailing an API endpoint means continuously calling it to get records
that are new or updated since your last request.

### Tail the Calls API endpoint

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

To tail the Calls API endpoint every 60 minutes, follow these steps:

1. Make a request to the Calls API endpoint (`/manager/api/v1/calls`), 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.

   The following is an example Bash script that uses the `curl` command:

       # 1. Define your environment variables (usually set in your shell or .env file)
       export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
       export API_USER="ccaip-host"
       export API_PASS="CCAI Platform API Key"

       # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
       # For macOS (BSD date):
       # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
       # For Linux (GNU date):
       TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")

       # 3. Execute the curl command
       # -u handles the Base64 encoding for Basic Auth automatically
       curl -g -u "${API_USER}:${API_PASS}" \
       "https://${API_HOSTNAME}/manager/api/v1/calls?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jq

   The Calls 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 the timestamp you specified 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. The `from` filter is inclusive, so the next response repeats the
   record at that timestamp. Deduplicate on record ID, or record the IDs
   already processed at that timestamp and skip them.
2. Call the Call API endpoint 60 minutes later. The updated Call
   records since your last request are returned.

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

### Tail the Chats API endpoint

Use the `updated_at` timestamp from the last object in this response for the timestamp in your next call to the endpoint. The `updated_at[from]` filter is inclusive, so the next response repeats the record at that timestamp. Deduplicate on record ID, or record the IDs already processed at that timestamp and skip them.

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

To tail the Chats API endpoint every 60 minutes, follow these steps:

1. Make a request to the Chats API endpoint (`/manager/api/v1/chats`), 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.

   The following is an example Bash script that uses the `curl` command:

       # 1. Define your environment variables (usually set in your shell or .env file)
       export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com/"
       export API_USER="ccaip-host"
       export API_PASS="CCAI Platform API Key"

       # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
       # For macOS (BSD date):
       # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
       # For Linux (GNU date):
       TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")

       # 3.. Execute the curl command
       # -u handles the Base64 encoding for Basic Auth automatically
       curl -g -u "${API_USER}:${API_PASS}" \
       "https://${API_HOSTNAME}/manager/api/v1/chats?updated_at[from]=${TIMESTAMP}&sort_column=updated_at&sort_direction=asc" | jq

   The Chats 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 the timestamp specified 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.
2. Call the API endpoint again 60 minutes later. The updated chat
   records since your last request are returned.

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

### Tail the Agent Activity API endpoint

Unlike the Chat and Call records, the Agent Activity Logs don't get updated and
as such don't have an `updated_at` timestamp. You can use the `started_at`
timestamp to specify the activity records that you want to retrieve when calling
the Agent Activity API endpoint. The `started_at[from]` filter is inclusive,
so the next response repeats the record at that timestamp. Deduplicate on
record ID, or record the IDs already processed at that timestamp and skip them.

To tail the Agent Activity API endpoint every 60 minutes, follow these steps:

1. Make a request to the Agent Activity API endpoint (`/manager/api/v1/agent_activity_logs`), specifying the following query parameters:

   - `started_at[from]`. Specify that you want activity logs that were
     started on or after this time.

   - `ended_at[from]`. Specify that you want activity logs that ended on or
     after this time. Use this instead of `started_at[from]` to catch
     sessions that started before your window but ended inside it.

   - `page`. Include this parameter so the response returns pagination
     headers. Without `page`, the response is capped at the default page
     size of 100 records without returning the `Link`, `Total` or `Per-Page`
     headers.

   - `sort_column`. Specify the field to sort the records by.

   - `sort_direction`. Specify the sort direction of the records in the
     response.

   The following is an example Bash script that uses the `curl` command:

       # 1. Define your environment variables (usually set in your shell or .env file)
       export API_HOSTNAME="ccaip-host.uc1.ccaiplatform.com"
       export API_USER="ccaip-host"
       export API_PASS="CCAI Platform API Key"

       # 2. Calculate the timestamp for 60 minutes ago in ISO 8601 format (UTC)
       # For macOS (BSD date):
       # TIMESTAMP=$(date -v-60M -u +"%Y-%m-%dT%H:%M:%SZ")
       # For Linux (GNU date):
       TIMESTAMP=$(date --date='60 minutes ago' -u +"%Y-%m-%dT%H:%M:%SZ")

       # 3. Execute the curl command
       # -u handles the Base64 encoding for Basic Auth automatically
       curl -g -u "${API_USER}:${API_PASS}" \
       "https://${API_HOSTNAME}/manager/api/v1/agent_activity_logs?started_at[from]=${TIMESTAMP}&sort_column=started_at&sort_direction=asc" | jq

   The Agent Activity API returns a response similar to the following:

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

   Response objects started on or after the timestamp specified are returned,
   sorted by date, in ascending order. Use the `started_at` timestamp from the
   last object in this response for the timestamp in your next call to the
   endpoint.
2. Call the Agent Activity API endpoint again 60 minutes later. The
   updated Agent Activity Log records since your last request are returned.

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