Run a report query
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"query": {
"fields": [
"datamart_claudia__claudia_conversation.creation_date[week]",
"datamart_claudia__claudia_conversation.taxa_retencao_pct"
],
"from": "2026-09-21",
"to": "2026-10-11",
"sorts": [
{
"field": "datamart_claudia__claudia_conversation.creation_date[week]"
}
]
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries"
payload = { "query": {
"fields": ["datamart_claudia__claudia_conversation.creation_date[week]", "datamart_claudia__claudia_conversation.taxa_retencao_pct"],
"from": "2026-09-21",
"to": "2026-10-11",
"sorts": [{ "field": "datamart_claudia__claudia_conversation.creation_date[week]" }]
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: {
fields: [
'datamart_claudia__claudia_conversation.creation_date[week]',
'datamart_claudia__claudia_conversation.taxa_retencao_pct'
],
from: '2026-09-21',
to: '2026-10-11',
sorts: [{field: 'datamart_claudia__claudia_conversation.creation_date[week]'}]
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries', 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}/report-queries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => [
'fields' => [
'datamart_claudia__claudia_conversation.creation_date[week]',
'datamart_claudia__claudia_conversation.taxa_retencao_pct'
],
'from' => '2026-09-21',
'to' => '2026-10-11',
'sorts' => [
[
'field' => 'datamart_claudia__claudia_conversation.creation_date[week]'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries"
payload := strings.NewReader("{\n \"query\": {\n \"fields\": [\n \"datamart_claudia__claudia_conversation.creation_date[week]\",\n \"datamart_claudia__claudia_conversation.taxa_retencao_pct\"\n ],\n \"from\": \"2026-09-21\",\n \"to\": \"2026-10-11\",\n \"sorts\": [\n {\n \"field\": \"datamart_claudia__claudia_conversation.creation_date[week]\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": {\n \"fields\": [\n \"datamart_claudia__claudia_conversation.creation_date[week]\",\n \"datamart_claudia__claudia_conversation.taxa_retencao_pct\"\n ],\n \"from\": \"2026-09-21\",\n \"to\": \"2026-10-11\",\n \"sorts\": [\n {\n \"field\": \"datamart_claudia__claudia_conversation.creation_date[week]\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": {\n \"fields\": [\n \"datamart_claudia__claudia_conversation.creation_date[week]\",\n \"datamart_claudia__claudia_conversation.taxa_retencao_pct\"\n ],\n \"from\": \"2026-09-21\",\n \"to\": \"2026-10-11\",\n \"sorts\": [\n {\n \"field\": \"datamart_claudia__claudia_conversation.creation_date[week]\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"topic": {
"key": "claudia_conversations",
"name": "ClaudIA Conversations"
},
"period": {
"from": "2026-09-21",
"to": "2026-10-11",
"axis": "conversation_created"
},
"fields": [
"datamart_claudia__claudia_conversation.creation_date[week]",
"datamart_claudia__claudia_conversation.taxa_retencao_pct"
],
"filters": [],
"projects": [
"<YOUR_PROJECT>"
],
"rows": [
{
"datamart_claudia__claudia_conversation.creation_date[week]": "2026-09-21",
"datamart_claudia__claudia_conversation.taxa_retencao_pct": 57.2
},
{
"datamart_claudia__claudia_conversation.creation_date[week]": "2026-09-28",
"datamart_claudia__claudia_conversation.taxa_retencao_pct": 54.21
},
{
"datamart_claudia__claudia_conversation.creation_date[week]": "2026-10-05",
"datamart_claudia__claudia_conversation.taxa_retencao_pct": 59.47
}
],
"truncated": false
}{
"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": "fields",
"code": "inclusion",
"message": "Unknown fields: <FIELD>. List the available ones with the query fields endpoint"
}
]
}
}{
"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."
}
}Reports
Run a report query
Runs a query you build from the fields of list report query fields, over the ClaudIA projects you can access. The rows are split by every dimension you ask for, with each measure aggregated within the split, like a pivot table.
Reading data does not change anything, even though the call is a POST. The data is refreshed periodically, not in real time, and the same query within 10 minutes returns the cached answer. For the dashboard metrics, use get a report.
POST
/
v1
/
accounts
/
{accountId}
/
report-queries
Run a report query
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"query": {
"fields": [
"datamart_claudia__claudia_conversation.creation_date[week]",
"datamart_claudia__claudia_conversation.taxa_retencao_pct"
],
"from": "2026-09-21",
"to": "2026-10-11",
"sorts": [
{
"field": "datamart_claudia__claudia_conversation.creation_date[week]"
}
]
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries"
payload = { "query": {
"fields": ["datamart_claudia__claudia_conversation.creation_date[week]", "datamart_claudia__claudia_conversation.taxa_retencao_pct"],
"from": "2026-09-21",
"to": "2026-10-11",
"sorts": [{ "field": "datamart_claudia__claudia_conversation.creation_date[week]" }]
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: {
fields: [
'datamart_claudia__claudia_conversation.creation_date[week]',
'datamart_claudia__claudia_conversation.taxa_retencao_pct'
],
from: '2026-09-21',
to: '2026-10-11',
sorts: [{field: 'datamart_claudia__claudia_conversation.creation_date[week]'}]
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries', 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}/report-queries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => [
'fields' => [
'datamart_claudia__claudia_conversation.creation_date[week]',
'datamart_claudia__claudia_conversation.taxa_retencao_pct'
],
'from' => '2026-09-21',
'to' => '2026-10-11',
'sorts' => [
[
'field' => 'datamart_claudia__claudia_conversation.creation_date[week]'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries"
payload := strings.NewReader("{\n \"query\": {\n \"fields\": [\n \"datamart_claudia__claudia_conversation.creation_date[week]\",\n \"datamart_claudia__claudia_conversation.taxa_retencao_pct\"\n ],\n \"from\": \"2026-09-21\",\n \"to\": \"2026-10-11\",\n \"sorts\": [\n {\n \"field\": \"datamart_claudia__claudia_conversation.creation_date[week]\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": {\n \"fields\": [\n \"datamart_claudia__claudia_conversation.creation_date[week]\",\n \"datamart_claudia__claudia_conversation.taxa_retencao_pct\"\n ],\n \"from\": \"2026-09-21\",\n \"to\": \"2026-10-11\",\n \"sorts\": [\n {\n \"field\": \"datamart_claudia__claudia_conversation.creation_date[week]\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/report-queries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": {\n \"fields\": [\n \"datamart_claudia__claudia_conversation.creation_date[week]\",\n \"datamart_claudia__claudia_conversation.taxa_retencao_pct\"\n ],\n \"from\": \"2026-09-21\",\n \"to\": \"2026-10-11\",\n \"sorts\": [\n {\n \"field\": \"datamart_claudia__claudia_conversation.creation_date[week]\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"topic": {
"key": "claudia_conversations",
"name": "ClaudIA Conversations"
},
"period": {
"from": "2026-09-21",
"to": "2026-10-11",
"axis": "conversation_created"
},
"fields": [
"datamart_claudia__claudia_conversation.creation_date[week]",
"datamart_claudia__claudia_conversation.taxa_retencao_pct"
],
"filters": [],
"projects": [
"<YOUR_PROJECT>"
],
"rows": [
{
"datamart_claudia__claudia_conversation.creation_date[week]": "2026-09-21",
"datamart_claudia__claudia_conversation.taxa_retencao_pct": 57.2
},
{
"datamart_claudia__claudia_conversation.creation_date[week]": "2026-09-28",
"datamart_claudia__claudia_conversation.taxa_retencao_pct": 54.21
},
{
"datamart_claudia__claudia_conversation.creation_date[week]": "2026-10-05",
"datamart_claudia__claudia_conversation.taxa_retencao_pct": 59.47
}
],
"truncated": false
}{
"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": "fields",
"code": "inclusion",
"message": "Unknown fields: <FIELD>. List the available ones with the query fields endpoint"
}
]
}
}{
"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.
Example:
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.
Example:
1
Body
application/json
Response
The rows of the query.
The rows of one query.
The topic the query ran on.
Show child attributes
Show child attributes
The period the rows cover.
Show child attributes
Show child attributes
The fields asked for, in the order sent.
The filters applied, except the project filter, which projects reflects.
Show child attributes
Show child attributes
The ClaudIA projects the query covered.
The rows, keyed by field name. NUMBER values are numbers, BOOLEAN values are booleans, other values are text (a week reads 2026-09-21), and a missing value is null.
true when more rows exist than limit, or the rows hit the response size cap. Narrow the period or the filters, or raise limit.
Present only when something limited the answer, and then rows is empty. no_claudia_projects: you can access no ClaudIA project on this account. no_matching_projects: the project filter left none of yours.