How to extract data in bulk via API (Data Extract API)

When to use it

• You need to export historical ticket data for BI, auditing or an external dashboard
• You want to feed custom reports with complete Cloud Chat data
• You need to track delivery events from campaigns and proactive messages

Prerequisites

• API Key generated by an administrator or supervisor user — see How to find your API Key in Cloud Chat

• CLOUDCHAT_DOMAIN and ACCOUNT_ID

• An extraction period of at most 5 days (120 hours) per request

About this article

The Data Extract API lets you export complete data from your tickets directly from your Cloud Chat account — dates, statuses, owners, response times and much more. Ideal for custom reports and external integrations.

Base request

curl --location 'https://{CLOUDCHAT_DOMAIN}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T01:58:59&endDate=2025-03-28T01:59:00&type=BASE_TICKET_METRICS' \
  --header 'Accept: application/json' \
  --header 'api_access_token: {API_TOKEN}'

Where to find the parameters

• CLOUDCHAT_DOMAIN — part of the URL when you log in to your account

  

• ACCOUNT_ID — after logging in, the ID appears in the URL as app/accounts/{id}/dashboard. E.g.: in cloudhumans.com/app/accounts/1/conversations/6341 the account_id is 1

• API_TOKEN — generate it from an administrator or supervisor profile (under "Configurações do perfil" (Profile settings), in your own environment — use your account's domain, e.g.: https://YOUR-DOMAIN.cloudhumans.com/app/accounts/{ACCOUNT_ID}/profile/settings. The domain varies by instance: cloudchat, cloudchat2, cloudchat3…)

  

Required parameters

• startDate — Start date and time (UTC) in the yyyy-MM-ddTHH:mm:ss format. E.g.: 2025-03-27T01:58:59

• endDate — End date and time (UTC). It must be later than startDate and the interval cannot exceed 5 days (120 hours). E.g.: 2025-03-28T01:59:00

• type — Type of data to export (see the list below)

• account_id — Account ID, provided in the URL path

Available types

• BASE_TICKET_METRICS

• TICKET_METRICS_WITH_AGENT_INFORMATION

• TICKET_SUMMARY

• CAMPAIGN_DELIVERY_EVENTS

• SINGLE_CONTACT_DELIVERY_EVENTS

Optional parameter: rangeFilterProperty

Defines which date field is used to apply the period filters.

Date range

Request limit (rate limit)

The Data Extract API applies a limit of 20 requests per minute per token. Different tokens from the same account have independent budgets.

What happens when you exceed the limit

Requests beyond the limit receive HTTP 429 Too Many Requests:

{
  "error": "Rate limit exceeded. Retry later.",
  "retry_after": 42
}

Recommendations

1. BASE_TICKET_METRICS

Returns basic ticket data. Returned fields:

Response example

[
  {
    "ticketId": 123456,
    "displayTicketId": 7890,
    "inboxId": 101,
    "accountId": 42,
    "accountName": "Minha Empresa",
    "ticketStatus": "resolved",
    "teamName": "Meu Time",
    "ticketPriorityName": "High",
    "ticketType": "suporte",
    "inboxName": "WhatsApp",
    "ticketTitle": "+5511999999999",
    "channel": "Whatsapp",
    "createdAt": "2025-03-27T09:53:14.791Z",
    "firstReplyAt": "2025-03-27T10:09:29.225Z",
    "firstReplyTime": 16.24,
    "resolvedAt": "2025-03-27T13:20:15.830Z",
    "totalResolutionTimeMin": 207.01,
    "tags": "suporte,prioridade_alta",
    "agentId": 42,
    "ticketOwner": "ClaudIA",
    "ticketOwnerEmail": "[email protected]",
    "contactId": 998877,
    "contactName": "Contact Name",
    "contactEmail": "[email protected]",
    "contactPhone": "+5511887774411",
    "campaignId": 123,
    "proactivelyInitiated": true
  }
]

2. TICKET_METRICS_WITH_AGENT_INFORMATION

Includes details about the agent who replied and resolved. Additional fields:

Response example

[
  {
    "ticketId": 11111,
    "displayTicketId": 11111,
    "accountName": "account name",
    "inboxName": "WhatsApp",
    "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/11111",
    "ticketStatus": "resolved",
    "createdAt": "2025-03-27T13:00:40.897954",
    "resolvedAt": "2025-03-27T15:38:02.743726",
    "agentOnResolutionId": 225,
    "agentOnResolutionName": "ClaudIA",
    "agentOnResolutionEmail": "[email protected]",
    "firstAgentReplyId": 111,
    "firstAgentReplyName": "ClaudIA",
    "firstAgentReplyEmail": "[email protected]",
    "firstAgentAssignmentTime": "2025-03-27T13:16:13.001269",
    "firstAgentFirstReplyTime": "2025-03-27T13:17:01.344971",
    "firstAgentReplyTimeMin": 0.81,
    "firstAgentResolutionTimeMin": 141.83,
    "csatScore": null,
    "csatFeedback": "",
    "contactCustomFields": "{}",
    "conversationCustomFields": "{}",
    "conversationAdditionalFields": "{}"
  }
]

3. TICKET_SUMMARY

Returns a summary of the ticket conversation. Returned fields:

[
  {
    "ticketId": 1111,
    "displayTicketId": 1111,
    "ticketLink": "https://cloudchat.cloudhumans.com/app/accounts/99999/conversations/1111",
    "summary": "CONTATO: Oi\nUSUÁRIO: Olá!"
  }
]

4. CAMPAIGN_DELIVERY_EVENTS

Returns WhatsApp campaign delivery events, tracking message status by contact and campaign.

Returned fields:

Response example

[
  {
    "id": 103,
    "campaignId": 5502,
    "campaignTitle": "Natal 2025 - Promoção Especial",
    "audience": "lista_fidelidade_natal",
    "contactId": 9003,
    "contactName": "Carla Souza",
    "contactEmail": "[email protected]",
    "contactPhoneNumber": "+55 31 99999-99999",
    "ticketId": 78414,
    "displayTicketId": "2027",
    "messageSent": false,
    "sentAt": null,
    "messageReceived": false,
    "receivedAt": null,
    "messageRead": false,
    "readAt": null,
    "messageReplied": false,
    "repliedAt": null,
    "error": "Número de telefone inválido ou não registrado no WhatsApp",
    "createdAt": "2025-12-10T09:00:00.000Z",
    "updatedAt": "2025-12-10T09:00:00.000Z"
  }
]

5. SINGLE_CONTACT_DELIVERY_EVENTS

Returns delivery events of proactive single-send messages (not campaigns). Returned fields:

Response example

[
  {
    "id": 321,
    "contactId": 555777,
    "contactName": "Maria Silva",
    "contactEmail": "[email protected]",
    "contactPhoneNumber": "+55 11 98888-7777",
    "ticketId": 78414,
    "displayTicketId": "2027",
    "messageSent": true,
    "sentAt": "2025-08-01T12:00:05.000Z",
    "messageReceived": true,
    "receivedAt": "2025-08-01T12:00:08.000Z",
    "messageRead": true,
    "readAt": "2025-08-01T12:01:30.000Z",
    "messageReplied": false,
    "repliedAt": null,
    "error": null,
    "createdAt": "2025-08-01T11:59:59.000Z",
    "updatedAt": "2025-08-01T12:01:30.000Z"
  }
]

Practical step by step

1. Generate your API Key in an administrator or supervisor profile ("Configurações do perfil" (Profile settings) → see "How to find your API Key").
2. Choose where to run it: it is an HTTP GET call — use an API client (Postman, Insomnia) or the terminal with curl. No programming required.
3. Build the URL replacing the fields between {}: https://{YOUR_DOMAIN}/api/v2/accounts/{ACCOUNT_ID}/data_extracts?startDate=2025-03-27T00:00:00&endDate=2025-03-27T23:59:59&type=TICKET_METRICS_WITH_AGENT_INFORMATION
4. Add the authentication header (required — without it, it returns 401): api_access_token: {YOUR_API_KEY}
5. Send the request (Send button in Postman, or run the curl).
6. Read the result: you get a JSON with the list of tickets; each field is described in the type tables of this article.

Notes

• For real-time queries (not historical): How to query contacts, tickets and messages in real time via API

• To change ticket data via API: How to update and act on tickets via API

• Overview of all available APIs: Master Guide — How to access and operate Cloud Chat data via API