> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # 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_through` is the newest matching conversation, not a refresh time. - **Shape.** Each metric returns `rows` as its tile computes them, keyed by the column labels it shows, plus `value` when the result is a single number. Some tiles are a series even without `group_by` (CSAT by week, transfer reasons by day); their first bucket can be dated before `from` but holds only days inside the period. - **Period.** Send `from` and `to` together, both included. Without them the dashboard's default period applies, and the response does not say which dates it covered (`period.from` and `period.to` are `null`). - **Filters.** Filter values must match the data exactly: one that matches nothing returns zeros and a `null` `data_through`, not an error. - **Partial answers.** A heavy call can return some metrics with `timed_out` set to `true` and `warnings` including `partial_results`. - **Comparing periods.** There is no previous-period value. Prefer one call over the whole span with `group_by` set to `week` or `month`; 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`. ## OpenAPI ````yaml api-reference/specs/cloudchat/v1.json GET /v1/accounts/{accountId}/reports/{reportKey} openapi: 3.0.1 info: title: Cloud Chat API version: v1 description: >- The curated public surface of Cloud Chat. Every call needs two things: the Bearer token from `POST /auth/v1/signin`, and the `cloudchat-instance` header that says which Cloud Chat instance your company lives on. If you don't know your instance value, the [Find your credentials](/api-reference/cloudchat/credentials) page reads it out of your own token in the browser. servers: - url: https://api.cloudhumans.com/cloudchat description: Production security: - bearerAuth: [] tags: - name: Canned Responses description: >- Canned responses — the shortcuts agents expand while replying. Each one belongs to a single account and is identified by its short code. - name: Conversations description: >- Read-only access to the conversations of an account. What you can see follows the same rule as the dashboard: an administrator token sees every inbox, an agent token only the inboxes it is a member of. - name: Help Center description: >- Portals, categories and articles of the help center — the public FAQ your customers read. - name: Uploads description: Store the images help center articles embed. - name: Labels description: >- Read-only access to the labels an account has defined. A label is a tag conversations and contacts carry; this endpoint only lists the label definitions themselves. - name: Inboxes description: >- Read-only access to the inboxes a token can see — every inbox of the account for an administrator, only its memberships for an agent. Never includes the channel's credentials. - name: Agents description: >- Read-only access to the human and AI agents of an account. A hidden admin (the platform's own support user) never appears, on the list or by id. - name: Teams description: >- Teams group agents for assignment. Listing and reading are open to any member; creating and updating a team, and managing its membership, require an administrator token. A system-managed team (provisioned by the platform) can be read like any other but never updated. - name: Macros description: >- Macros bundle a sequence of actions an agent runs against a conversation from the dashboard. This surface lets you list, read and write macro definitions — running one is not part of the v1 contract. A macro is either `global` (visible to the whole account) or `personal` (visible only to its author); an agent token can only create personal macros. - name: Automation Rules description: >- Read-only access to the account's automation rules — administrator only. An agent token gets a 403 on every operation in this group. - name: Availability Reasons description: >- The reasons an agent can go `busy` for, configured per account. Listing is open to any member; creating, updating and deleting require an administrator token. Deleting is a soft delete — the reason disappears from listings but agents' past availability history keeps referencing it. - name: Native Attribute Requirements description: >- Which native conversation attributes (priority, assignee, tag, team) the account requires agents to fill before resolving a conversation. Listing is open to any member; requiring and un-requiring need an administrator token. Deleting a requirement is reversible — require the same key again to restore it. - name: Campaigns description: Check who a campaign would reach, send it, and read the result back. - name: Reports description: The numbers of the Cloud Chat reporting dashboards, read through the API. paths: /v1/accounts/{accountId}/reports/{reportKey}: parameters: - $ref: '#/components/parameters/CloudChatInstance' - $ref: '#/components/parameters/AccountId' - name: reportKey in: path required: true description: >- The report to read, as `key` in [list reports](/api-reference/cloudchat/endpoints/list-reports). schema: type: string example: claudia_general_info get: tags: - Reports summary: Get a report description: >- 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_through` is the newest matching conversation, not a refresh time. - **Shape.** Each metric returns `rows` as its tile computes them, keyed by the column labels it shows, plus `value` when the result is a single number. Some tiles are a series even without `group_by` (CSAT by week, transfer reasons by day); their first bucket can be dated before `from` but holds only days inside the period. - **Period.** Send `from` and `to` together, both included. Without them the dashboard's default period applies, and the response does not say which dates it covered (`period.from` and `period.to` are `null`). - **Filters.** Filter values must match the data exactly: one that matches nothing returns zeros and a `null` `data_through`, not an error. - **Partial answers.** A heavy call can return some metrics with `timed_out` set to `true` and `warnings` including `partial_results`. - **Comparing periods.** There is no previous-period value. Prefer one call over the whole span with `group_by` set to `week` or `month`; 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`. operationId: getReport parameters: - name: metrics in: query required: false description: >- Comma-separated metric keys from [list reports](/api-reference/cloudchat/endpoints/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. schema: type: string example: retention,volume - name: from in: query required: false description: >- First day of the period, `YYYY-MM-DD`, included. Send it together with `to`. schema: type: string example: '2026-09-21' - name: to in: query required: false description: >- Last day of the period, `YYYY-MM-DD`, included. Send it together with `from`. schema: type: string example: '2026-10-11' - name: group_by in: query required: false description: >- 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. schema: type: string example: week - name: project in: query required: false description: >- 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. schema: type: string example: - name: closing in: query required: false description: >- Comma-separated values of the dashboard's **Fechamento** filter, in Portuguese exactly as stored: `Dentro do horário` or `Fora do horário`. schema: type: string example: Dentro do horário - name: resolution_reason in: query required: false description: >- Comma-separated resolution reasons, exactly as stored. This API does not list them. schema: type: string example: - name: tag in: query required: false description: >- Comma-separated conversation tags, exactly as stored. This API does not list them. schema: type: string example: - name: ab_test in: query required: false description: Comma-separated A/B test keys, exactly as stored. schema: type: string example: responses: '200': description: The numbers of the report. content: application/json: schema: $ref: '#/components/schemas/ReportResult' example: 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 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ReportsForbidden' '404': $ref: '#/components/responses/ReportsNotFound' '422': $ref: '#/components/responses/ReportsValidationFailed' '429': $ref: '#/components/responses/ReportsTooManyRequests' '500': $ref: '#/components/responses/ReportsInternalError' '503': $ref: '#/components/responses/ReportsUnavailable' components: parameters: CloudChatInstance: name: cloudchat-instance in: header required: true description: >- Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. [The API overview](/api-reference/cloudchat/overview#two-headers-every-call) explains how instances work, how to find yours, and the errors a wrong or missing value produces. schema: type: integer example: 1 AccountId: name: accountId in: path required: true description: >- 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. schema: type: integer example: 1 schemas: ReportResult: type: object description: The numbers of one report. required: - report - period - filters - metrics - data_through_approximate properties: report: type: object description: Which report answered. required: - key - name properties: key: type: string description: The report key. name: type: string description: The report name, as Cloud Chat shows it. period: type: object description: The period the numbers cover. required: - dashboard_default - axis properties: from: type: string description: >- First day, `YYYY-MM-DD`. `null` when the dashboard default period applied. nullable: true to: type: string description: >- Last day, `YYYY-MM-DD`, included. `null` when the dashboard default period applied. nullable: true dashboard_default: type: boolean description: >- `true` when you sent no `from`/`to` and the dashboard default period applied. axis: type: string description: >- Which date the period filters on, as `date_axis` in the report list. filters: type: object description: >- The filters applied, by parameter, each with the values you sent. Empty when you sent none. additionalProperties: type: array items: type: string group_by: type: string description: >- The period the series were split by, or `null` for the dashboard default. nullable: true metrics: type: array description: The metrics you asked for, in the report order. items: $ref: '#/components/schemas/ReportMetric' data_through: type: string description: >- 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. nullable: true data_through_approximate: type: boolean description: Always `true`; see `data_through`. warnings: type: array description: >- 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`. items: type: string ReportMetric: type: object description: One metric of the report. required: - key - rows - truncated - timed_out properties: key: type: string description: The metric key. name: type: string description: >- The metric name as the dashboard shows it, in the dashboard's language. nullable: true columns: type: array description: >- The columns of `rows`, in order: the key each row uses and the label the dashboard shows for it. items: type: object required: - key - label properties: key: type: string description: The key of this column in each row. label: type: string description: The column label as the dashboard shows it. rows: type: array description: >- The rows as the tile computes them, keyed by column key (see `columns` for labels). Dates come as `YYYY-MM-DD`, numbers as numbers and an empty cell as `null`: no data, not zero. Prefer `value` when present. Empty when `timed_out` is `true`. items: type: object additionalProperties: true truncated: type: boolean description: >- `true` when `rows` hit the row cap, so more rows may exist. Narrow the period or the filters to get them all. timed_out: type: boolean description: >- `true` when this metric did not finish in time; `rows` is then empty. Retry the same call or only these metrics: finished ones come back quickly. value: type: number description: >- Present only when the result is a single number, such as a rate or a total. Absent with `group_by`. Error: type: object description: The error envelope every Cloud Chat API response uses. required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- The stable, machine-readable reason. Branch on this, never on `message`. enum: - unauthorized - forbidden - not_found - validation_failed - bad_request - internal_error - rate_limited - service_unavailable example: not_found message: type: string description: >- The reason in words, localized to your account's language (English, Spanish or Brazilian Portuguese; English when the account is set to anything else). Wording changes with the account and between releases, so never match on it. Two cases stay in English whatever the account is set to: `unauthorized`, decided before any account is known, and the account-level `not_found`, which must not reveal the account's language. example: Resource could not be found. details: type: array description: >- Present on some rejections — a 400 for a refused query parameter or upload mode, for example. One entry per offending field, localized to the account's language like `message` — match on `code` and `field`, never on the text. items: type: object required: - field - code - message properties: field: type: string description: Which request field the rule was about. code: type: string description: Stable, machine-readable reason. message: type: string description: The rule in words. ValidationError: type: object description: A `validation_failed` error, which carries `details`. required: - error properties: error: type: object required: - code - message - details properties: code: type: string enum: - validation_failed example: validation_failed message: type: string description: >- Localized to the account's language, like every other envelope message. example: The request payload is invalid. details: type: array description: >- One entry per rejected field. Unlike the envelope message above, the texts come from the model layer and are in English in practice (the model layer ships no translations) — match on code and field, never on the text. items: type: object required: - field - code - message properties: field: type: string description: >- Which request field the rule was about — `short_code` or `content`. A rule that is not tied to either is reported as `base`, so treat `base` as "the payload as a whole" rather than a field you can highlight. enum: - short_code - content - base example: short_code code: type: string description: >- Which rule it broke — `blank` for a missing or empty value, `taken` for a `short_code` already used on the account. example: taken message: type: string example: has already been taken GatewayError: type: object description: >- Rejected by the gateway before Cloud Chat saw it, so it does not use the `error` envelope. required: - message properties: message: type: string example: API rate limit exceeded request_id: type: string description: Gateway request id. Quote it when reporting a problem. example: f3f7567638d4b65a8003057d0c77d275 responses: BadRequest: description: >- The request itself is malformed, before any value is validated: - a body that isn't valid JSON, or one with no `canned_response` wrapper, - a `canned_response` that isn't an object (`{"canned_response": "text"}`), - `page`, `per_page`, `search` or `sort` sent as an array or a nested object (`?page[]=1`, `?sort[x]=y`) instead of a plain value, - **the `cloudchat-instance` header missing or holding a value we don't route,** - an `accountId` that is not a number — including the literal `{accountId}` that some API clients send when the argument is left unset. This one answers with the normal envelope and `error.details` naming `accountId`, and it is deliberately **not** a 404: a 404 would mean the account cannot be reached, while this means the value was never an account id at all, so re-read the argument instead of trying other numbers. **Two different shapes answer with 400, and the difference will bite you on day one.** That last case is rejected before the request reaches the API, so `error` is a plain **string** instead of the usual object: ```json { "error": "" } ``` Every other 400 uses the normal envelope, where `error` is an object with `code` and `message`. Reading `error.code` without checking the type first throws on the missing-header case — which is the most likely 400 of your first integration. Check `typeof error === "string"` first, or read `error?.code` defensively. A 400 always means fix the request shape; it never means a value was rejected. Rejected values are 422. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: The request is malformed. Unauthorized: description: >- No Bearer token, or one that is expired, malformed, or not a Cognito token. Sign in again for a fresh `id_token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: >- Authentication is required. Send a valid Bearer token in the Authorization header. ReportsForbidden: description: >- Reading reports needs an administrator, supervisor or CX engineer role, or an agent role on an account that granted reports to its agents. A suspended account also answers `403`, and then nothing on it works until it is reactivated. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: You are not allowed to perform this action. ReportsNotFound: description: >- The account does not exist, you are not a member of it, reports are not enabled on it, or the `reportKey` does not exist. These cases are deliberately indistinguishable. Check `reportKey` against [list reports](/api-reference/cloudchat/endpoints/list-reports) before anything else. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Resource could not be found. ReportsValidationFailed: description: >- A value the report cannot accept. `error.details` names each one and what it accepts. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: code: validation_failed message: The request payload is invalid. details: - field: metrics code: inclusion message: >- Unknown metrics: . Available: volume, n1_retained, retention, csat_n1 ReportsTooManyRequests: description: >- Rate limited. The gateway answers `{ "message": ... }`, with `Retry-After` and the `ratelimit-*` headers carrying the current values. Other limits answer the usual envelope with code `rate_limited` and can apply even when your account made few calls: wait a minute before retrying. Don't hardcode any limit. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GatewayError' - $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Too many requests. Wait a minute and try again. ReportsInternalError: description: >- Something broke on our side. It is reported to our monitoring automatically. Retrying the same call will not help until it is fixed. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An unexpected error occurred. Please try again later. ReportsUnavailable: description: >- The reporting backend is unavailable, or no metric finished in time. Retry in a few minutes; if it persists, ask for fewer metrics or a shorter period. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: service_unavailable message: >- The reporting service is temporarily unavailable. Try again in a few minutes. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `id_token` from `POST /auth/v1/signin`, sent as `Authorization: Bearer `. Not the `access_token` — that one does not carry the identity Cloud Chat authorizes on. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.