curl --request GET \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey} \
--header 'Authorization: Bearer <token>' \
--header 'cloudchat-instance: <cloudchat-instance>'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}"
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'cloudchat-instance': '<cloudchat-instance>', Authorization: 'Bearer <token>'}
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"report": {
"key": "claudia_general_info",
"name": "ClaudIA - Informações Gerais"
},
"period": {
"from": "2026-09-21",
"to": "2026-10-11",
"dashboard_default": false,
"axis": "conversation_created"
},
"filters": {},
"group_by": "week",
"metrics": [
{
"key": "retention",
"name": "Taxa de retenção",
"truncated": false,
"timed_out": false,
"columns": [
{
"key": "creation_date[week]",
"label": "Creation Date Week"
},
{
"key": "taxa_retencao_pct",
"label": "Taxa de retencao (%)"
}
],
"rows": [
{
"creation_date[week]": "2026-09-21",
"taxa_retencao_pct": 57.2
},
{
"creation_date[week]": "2026-09-28",
"taxa_retencao_pct": 54.21
},
{
"creation_date[week]": "2026-10-05",
"taxa_retencao_pct": 59.47
}
]
}
],
"data_through": "2026-10-14 19:39:58.556",
"data_through_approximate": true
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "metrics",
"code": "inclusion",
"message": "Unknown metrics: <KEY>. Available: volume, n1_retained, retention, csat_n1"
}
]
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute and try again."
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}{
"error": {
"code": "service_unavailable",
"message": "The reporting service is temporarily unavailable. Try again in a few minutes."
}
}Get a report
The numbers of one report for a period and a set of filters, the same its dashboard shows in Cloud Chat, restricted to the Claudia projects you can access.
- Freshness. Data is not real time, and
data_throughis the newest matching conversation, not a refresh time. - Shape. Each metric returns
rowsas its tile computes them, keyed by the column labels it shows, plusvaluewhen the result is a single number. Some tiles are a series even withoutgroup_by(CSAT by week, transfer reasons by day); their first bucket can be dated beforefrombut holds only days inside the period. - Period. Send
fromandtotogether, both included. Without them the dashboard’s default period applies, and the response does not say which dates it covered (period.fromandperiod.toarenull). - Filters. Filter values must match the data exactly: one that matches nothing returns zeros and a
nulldata_through, not an error. - Partial answers. A heavy call can return some metrics with
timed_outset totrueandwarningsincludingpartial_results. - Comparing periods. There is no previous-period value. Prefer one call over the whole span with
group_byset toweekormonth; call twice only for irregular periods.
Values the report cannot accept (unknown metrics or filters, a malformed, one-sided, reversed or too long period, an unsupported group_by, projects you cannot access) answer 422, and error.details says what is accepted. Query parameters this endpoint does not define are ignored, so check their spelling; any parameter sent as an array or an object answers 400.
curl --request GET \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey} \
--header 'Authorization: Bearer <token>' \
--header 'cloudchat-instance: <cloudchat-instance>'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}"
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'cloudchat-instance': '<cloudchat-instance>', Authorization: 'Bearer <token>'}
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/reports/{reportKey}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"report": {
"key": "claudia_general_info",
"name": "ClaudIA - Informações Gerais"
},
"period": {
"from": "2026-09-21",
"to": "2026-10-11",
"dashboard_default": false,
"axis": "conversation_created"
},
"filters": {},
"group_by": "week",
"metrics": [
{
"key": "retention",
"name": "Taxa de retenção",
"truncated": false,
"timed_out": false,
"columns": [
{
"key": "creation_date[week]",
"label": "Creation Date Week"
},
{
"key": "taxa_retencao_pct",
"label": "Taxa de retencao (%)"
}
],
"rows": [
{
"creation_date[week]": "2026-09-21",
"taxa_retencao_pct": 57.2
},
{
"creation_date[week]": "2026-09-28",
"taxa_retencao_pct": 54.21
},
{
"creation_date[week]": "2026-10-05",
"taxa_retencao_pct": 59.47
}
]
}
],
"data_through": "2026-10-14 19:39:58.556",
"data_through_approximate": true
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "metrics",
"code": "inclusion",
"message": "Unknown metrics: <KEY>. Available: volume, n1_retained, retention, csat_n1"
}
]
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a minute and try again."
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}{
"error": {
"code": "service_unavailable",
"message": "The reporting service is temporarily unavailable. Try again in a few minutes."
}
}Authorizations
The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.
Headers
Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.
1
Path Parameters
Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.
1
The report to read, as key in list reports.
"claudia_general_info"
Query Parameters
Comma-separated metric keys from list reports. Leave it out for the report's default_metrics. Asking for more than a call allows answers 422, and error.details gives the maximum.
"retention,volume"
First day of the period, YYYY-MM-DD, included. Send it together with to.
"2026-09-21"
Last day of the period, YYYY-MM-DD, included. Send it together with from.
"2026-10-11"
Break every metric into one row per period, replacing the tile's own grain; single-number metrics then come as a series without value. One of the report's group_by values.
"week"
Comma-separated Claudia project names to restrict to. Leave it out for every project you can access. A project you cannot access answers 422, and error.details lists the ones you can.
"<PROJECT_NAME>"
Comma-separated values of the dashboard's Fechamento filter, in Portuguese exactly as stored: Dentro do horário or Fora do horário.
"Dentro do horário"
Comma-separated resolution reasons, exactly as stored. This API does not list them.
"<REASON>"
Comma-separated conversation tags, exactly as stored. This API does not list them.
"<TAG>"
Comma-separated A/B test keys, exactly as stored.
"<AB_TEST_KEY>"
Response
The numbers of the report.
The numbers of one report.
Which report answered.
Show child attributes
Show child attributes
The period the numbers cover.
Show child attributes
Show child attributes
The filters applied, by parameter, each with the values you sent. Empty when you sent none.
Show child attributes
Show child attributes
The metrics you asked for, in the report order.
Show child attributes
Show child attributes
Always true; see data_through.
The period the series were split by, or null for the dashboard default.
Newest conversation matching the filters, regardless of the period, in local time without offset (Brasília for most accounts). null when nothing matches or when this lookup did not finish in time. Not a refresh time: an account without recent conversations shows an old date even when its data is current.
Present only when something limited the answer. no_claudia_projects: you can access no Claudia project on this account, so no metric was computed. partial_results: some metrics did not finish in time and have timed_out set to true.