Reports and metrics - Chatarmin CX Docs

Use the Chatarmin CX reporting API to track ticket volume, response times, satisfaction, and automation in your own dashboards.

Access and limits

Both endpoints extend the existing /public/v1 API. Send your API key in the cx-api-key header. The key needs analytics:read and must be assigned to a support agent. Configure it in Settings → API. Report queries enforce that agent’s dashboard permissions and channel, team, and agent restrictions. A metric appearing in the catalog does not grant permission to read its data.

Endpoint	Purpose	Rate tier
`GET /public/v1/reports/metrics`	Discover metric definitions	List: 60 requests/minute
`POST /public/v1/reports/query`	Read report results	Analytics: 10 requests/minute

Neither endpoint changes tickets or sends messages. See rate limits for retry guidance and the OpenAPI reference for complete response schemas.

Discover metrics

curl 'https://api.armin.cx/public/v1/reports/metrics' \
  -H "cx-api-key: $CX_API_KEY"

The response is { "success": true, "data": [...] }. It contains the complete static catalog, without pagination. Each entry has:

Field	Meaning
`id`	Metric identifier for `SHOW` and `VISUALIZE`, such as `new_tickets`
`label`, `description`	Display name and definition
`group`, `dataType`	Metric category and value type
`format`	`count`, `duration-seconds`, `percent`, `decimal`, or `currency-eur`
`aggregation`	`count`, `sum`, `median`, `average`, or `ratio`
`attribution`	Which event or snapshot determines the metric’s period
`denominator`	Optional explanation of the denominator or calculation
`snapshot`	Whether the metric describes the current state rather than historical activity
`higherIsBetter`	Whether an increase represents an improvement

The catalog contains no ticket records, customer information, workspace entity IDs, or internal data-source names. Labels and descriptions are in English. Cache this metadata rather than fetching it before every query. Not every metric supports every grouping or visualization.

Query report data

Start with one metric and a short period. Send JSON with exactly two fields: query and an IANA timezone, such as Europe/Vienna or UTC.

curl 'https://api.armin.cx/public/v1/reports/query' \
  -H "cx-api-key: $CX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"FROM tickets\nSHOW new_tickets\nDURING yesterday\nVISUALIZE new_tickets TYPE kpi","timezone":"Europe/Vienna"}'

The response uses { "success": true, "data": ... }. Inspect data.kind to interpret the result: for example, kpi contains value, previousValue, and format; time-series contains series and points. The request returns chart data, not an image or CSV export.

Query language

Write each clause on its own line. This is the CX report query language, not SQL: there are no arbitrary tables, joins, or SQL expressions.

Clause	Usage
`FROM tickets`	Required. Only the `tickets` dataset is supported.
`SHOW new_tickets, resolved_tickets`	Required. Use IDs from the metric catalog.
`DURING yesterday`	Required date range, or use `SINCE ... UNTIL ...` instead. Other named periods include `today`, `this_week`, `last_week`, `this_month`, and `last_month`.
`SINCE 2026-08-01 UNTIL 2026-08-07`	Explicit calendar dates in the supplied timezone. Includes the end date. Do not combine with `DURING`.
`WHERE status is_one_of open, resolved`	Optional filter. Repeat `WHERE` on separate lines to require multiple conditions.
`GROUP BY channel`	Optional category grouping.
`TIMESERIES day`	Optional time grouping: `hour`, `day`, `week`, or `month`.
`COMPARE TO previous_period`	Optional comparison for KPI and supported time-series reports; also accepts `previous_year`.
`ORDER BY new_tickets DESC`	Optional result ordering; use `ASC` or `DESC`.
`LIMIT 25`	Optional result limit, up to 1,000.
`OPTIONS {"showAverageRow":true}`	Optional allow-listed visualization options, for example on a data table.
`VISUALIZE new_tickets TYPE kpi`	Required. Select metrics from `SHOW` and a supported visualization. Use one metric for a KPI.

Common visualizations include kpi, line, area, grouped_bar, stacked_bar, horizontal_bar, and data_table. Charts require metrics with the same format. A data_table can mix formats and requires exactly one breakdown dimension. All metrics, including automation and CSAT, use FROM tickets; there are no separate message or survey datasets.

Query examples

Send each complete query below as the query string in the HTTP request above, with timezone: "Europe/Vienna". Dates and metric IDs stay in the same format in every example.

Daily ticket volume

Compare tickets created and tickets resolved on each day. These are different event populations, not necessarily the same tickets.

FROM tickets
SHOW new_tickets, resolved_tickets
TIMESERIES day
SINCE 2026-08-01 UNTIL 2026-08-07
VISUALIZE new_tickets, resolved_tickets TYPE line

Yesterday’s ticket KPI

Compare new demand with the preceding day.

FROM tickets
SHOW new_tickets
DURING yesterday
COMPARE TO previous_period
VISUALIZE new_tickets TYPE kpi

New tickets by channel

Rank channels by incoming ticket volume. Channel keys in results identify your workspace’s channels, not a universal list of channel names.

FROM tickets
SHOW new_tickets
GROUP BY channel
DURING last_week
ORDER BY new_tickets DESC
LIMIT 10
VISUALIZE new_tickets TYPE horizontal_bar

First response durations

Compare median waits for a qualifying human or AI reply with waits for a human reply. Both series return seconds; they are not averages.

FROM tickets
SHOW customer_first_response_time, human_first_response_time
TIMESERIES day
DURING last_week
VISUALIZE customer_first_response_time, human_first_response_time TYPE line

CSAT score and sample size

Keep the score next to the number of responses so you can judge small samples. A table allows the decimal score and count in one result.

FROM tickets
SHOW csat_average, csat_responses, low_csat_tickets
GROUP BY day
DURING last_month
ORDER BY label ASC
VISUALIZE csat_average, csat_responses, low_csat_tickets TYPE data_table

Automation savings and spend

Compare estimated savings with estimated spend in EUR. This is a same-format daily chart, not a billing reconciliation. These specialized automation metrics support KPIs, daily charts or tables, and action breakdowns except for AI spend. Do not mix them with unrelated ticket metrics or add category splits.

FROM tickets
SHOW money_saved, ai_spend
TIMESERIES day
DURING last_week
VISUALIZE money_saved, ai_spend TYPE line

Filtered team workload

Review resolved German-language tickets by team, including resolution duration. Repeated filters are combined with AND. status is the current ticket status, not its status at the time of creation. For filters such as team, channel, or human_agent, use your workspace’s entity IDs rather than display names.

FROM tickets
SHOW resolved_tickets, full_resolution_time
WHERE language is de
WHERE status is resolved
GROUP BY team
DURING last_week
ORDER BY resolved_tickets DESC
LIMIT 25
OPTIONS {"showAverageRow":false}
VISUALIZE resolved_tickets, full_resolution_time TYPE data_table

Current customer-waiting snapshot

Count open tickets waiting for information from the customer, not customers waiting for support. The date clause is required by the language but does not turn a snapshot into historical data. Do not add TIMESERIES or COMPARE TO to snapshots.

FROM tickets
SHOW awaiting_response_now
DURING today
VISUALIZE awaiting_response_now TYPE kpi

Read results

These are illustrative response shapes with invented values, not guaranteed results for the example periods. Rows and points are shortened. Use returned labels and keys rather than assuming translated labels or fixed channel IDs. A KPI returns a number and its format. previousValue can be null; historical KPIs may already include a prior-period value without an explicit comparison. An explicit COMPARE TO selects the comparison period. Snapshot KPIs have no historical comparison.

{
  "success": true,
  "data": { "kind": "kpi", "value": 42, "previousValue": 38, "format": "count" }
}

Time-series point values use keys from series. Explicit comparisons add series keys ending in __compare.

{
  "success": true,
  "data": {
    "kind": "time-series",
    "format": "count",
    "series": [
      { "key": "new_tickets", "label": "New tickets" },
      { "key": "resolved_tickets", "label": "Resolved" }
    ],
    "points": [
      { "date": "2026-08-01", "label": "Aug 1", "values": { "new_tickets": 42, "resolved_tickets": 35 } }
    ]
  }
}

A category result contains labeled values.

{
  "success": true,
  "data": {
    "kind": "category",
    "format": "count",
    "items": [{ "key": "channel_example", "label": "Support email", "value": 42 }]
  }
}

A table describes each column’s metric and format. Do not add or average daily percentages, medians, or averages to reconstruct a period KPI; query the KPI for that period instead.

{
  "success": true,
  "data": {
    "kind": "data_table",
    "rowDimension": "day",
    "columns": [
      { "measureId": "csat_average", "label": "CSAT", "format": "decimal" },
      { "measureId": "csat_responses", "label": "CSAT responses", "format": "count" },
      { "measureId": "low_csat_tickets", "label": "Low-CSAT tickets", "format": "count" }
    ],
    "rows": [
      { "key": "2026-08-01", "label": "Aug 1", "values": { "csat_average": 4.5, "csat_responses": 10, "low_csat_tickets": 1 } }
    ]
  }
}

Metric reference

All 50 registered metric IDs are listed below, grouped as in the discovery catalog. Aggregation, format, and attribution are the exact catalog values. You select the metric, not a custom aggregation function.

count counts the defined tickets, messages, surveys, actions, or events; sum adds values; average is an arithmetic mean; median is the middle observation; ratio divides the eligible numerator by its denominator.
duration-seconds returns seconds, currency-eur returns EUR, decimal returns a decimal value, and percent returns percentage points: 75 means 75%, not 0.75. CSAT scores use a 1-5 scale.
Attribution chooses the date population: ticket_created is a creation cohort; ticket_resolved, reply_event, reopen_event, reassignment_event, survey_submitted, action_executed, and order_paid refer to their respective events. agent_presence measures online-session time; mixed_events combines creation and resolution; current_snapshot means now.
Creation-cohort facts can change as tickets develop. In particular, messages and messages_per_ticket include recorded messages on tickets created in the period, not only messages sent during it. Use agent_messages for human public messages sent in the period.
Current snapshots cannot use time dimensions or historical comparisons. Backlog age is measured from creation, not from the last message. Even with an older date clause, a snapshot is not an end-of-period backlog reconstruction.
Rates use the denominators in their definitions below, within the applicable scope. A zero or empty result alone does not establish that no activity occurred: reporting data can be incomplete or awaiting updates. Validate important totals before using them for commitments or financial reporting.
csat_response_rate is a sent-survey cohort: scored submissions divided by surveys sent in the period. Its catalog attribution is survey_submitted, but this calculation uses the sent date, unlike the other CSAT metrics.
time_saved and money_saved are estimates based on your workspace’s action-time and hourly-rate assumptions. ai_spend converts recorded AI credits using a fallback EUR-per-credit rate; it is not your invoice or a guarantee of your contracted price. Although its catalog attribution is action_executed, spend is dated by AI run creation, including spend on days without tracked actions.

Volume and workload

Metric ID	Definition and denominator	Aggregation	Format	Attribution
`new_tickets`	Tickets created in the period.	`count`	`count`	`ticket_created`
`resolved_tickets`	Tickets resolved in the period.	`count`	`count`	`ticket_resolved`
`tickets_replied_to`	Distinct tickets receiving a tracked public support reply in the period.	`count`	`count`	`reply_event`
`answered_tickets`	Distinct tickets with a human or AI message attributed to an agent in the period.	`count`	`count`	`reply_event`
`reopened_tickets`	Distinct tickets reopened in the period, not the number of reopen events.	`count`	`count`	`reopen_event`
`backlog_now`	Open, unresolved tickets now.	`count`	`count`	`current_snapshot`
`backlog_over_24h`	Open tickets created more than 24 hours ago.	`count`	`count`	`current_snapshot`
`backlog_over_48h`	Open tickets created more than 48 hours ago.	`count`	`count`	`current_snapshot`
`awaiting_response_now`	Open tickets waiting for information from the customer, not waiting for support.	`count`	`count`	`current_snapshot`
`net_backlog_change`	New tickets minus resolved tickets in the period; not a reconstruction of every backlog transition.	`sum`	`count`	`mixed_events`
`messages`	Total customer, human, and AI messages on tickets created in the period.	`sum`	`count`	`ticket_created`
`agent_messages`	Public business messages sent by human agents in the period.	`count`	`count`	`reply_event`
`messages_per_ticket`	Customer, human, and AI messages divided by tickets created in the period.	`average`	`decimal`	`ticket_created`
`agent_online_time`	Total agent online time in the inbox during the period; not ticket handling time.	`sum`	`duration-seconds`	`agent_presence`
`one_touch_tickets`	Resolved tickets with exactly one public support reply and no reopen.	`count`	`count`	`ticket_resolved`
`one_touch_rate`	One-touch tickets divided by resolved tickets.	`ratio`	`percent`	`ticket_resolved`
`zero_touch_tickets`	Resolved tickets with no human reply; does not mean no AI or automation activity.	`count`	`count`	`ticket_resolved`
`reassignments`	Assignment-change events in the period; a ticket can contribute more than once.	`count`	`count`	`reassignment_event`
`reassignment_rate`	Reassigned tickets divided by tickets created in the period.	`ratio`	`percent`	`ticket_created`
`demand_coverage`	Created tickets that reached final resolution divided by new tickets in the period, not resolved throughput divided by new demand.	`ratio`	`percent`	`ticket_created`
`support_revenue`	Shopify order revenue attributed to support tickets, in EUR, by order paid date.	`sum`	`currency-eur`	`order_paid`

Response and resolution

Metric ID	Definition and denominator	Aggregation	Format	Attribution
`customer_first_response_time`	Median wait for the first qualifying human or AI reply.	`median`	`duration-seconds`	`reply_event`
`human_first_response_time`	Median wait for the first qualifying human reply.	`median`	`duration-seconds`	`reply_event`
`ai_first_response_time`	Median wait for the first qualifying AI reply.	`median`	`duration-seconds`	`reply_event`
`full_resolution_time`	Median wall-clock time from ticket creation to resolution.	`median`	`duration-seconds`	`ticket_resolved`
`active_resolution_time`	Median business-hours time from creation to resolution, minus customer-waiting periods.	`median`	`duration-seconds`	`ticket_resolved`
`waiting_on_customer_time`	Median total customer-waiting time per resolved ticket, within business hours. Each ticket’s total sums its human-support-reply to next-customer-reply intervals.	`median`	`duration-seconds`	`ticket_resolved`
`sla_resolution_met`	Resolution SLA deadlines met on time for tickets created in the period.	`count`	`count`	`ticket_created`
`sla_resolution_breached`	Resolution SLA deadlines breached for tickets created in the period.	`count`	`count`	`ticket_created`

Quality and satisfaction

Metric ID	Definition and denominator	Aggregation	Format	Attribution
`reopen_rate`	Resolved tickets with a reopen divided by resolved tickets.	`ratio`	`percent`	`ticket_resolved`
`csat_average`	Average 1-5 score from scored surveys submitted in the period.	`average`	`decimal`	`survey_submitted`
`csat_responses`	Scored surveys submitted in the period.	`count`	`count`	`survey_submitted`
`csat_response_rate`	Surveys sent in the period that received a score divided by surveys sent; see the sent-date exception above.	`ratio`	`percent`	`survey_submitted`
`low_csat_tickets`	Distinct tickets with a submitted score of 3 or lower.	`count`	`count`	`survey_submitted`

AI and automation

Metric ID	Definition and denominator	Aggregation	Format	Attribution
`ai_involved_tickets`	Tickets created in the period where an AI agent ran or completed a tracked action.	`count`	`count`	`ticket_created`
`ai_resolved_tickets`	Tickets whose final outcome was resolved by an AI agent.	`count`	`count`	`ticket_resolved`
`ai_resolution_rate`	AI-resolved tickets divided by AI-involved resolved tickets, not all incoming tickets.	`ratio`	`percent`	`ticket_resolved`
`human_handoffs`	Resolved tickets with a recorded AI-to-human handoff, dated by resolution rather than handoff time.	`count`	`count`	`ticket_resolved`
`handoff_rate`	Human handoffs divided by AI-involved resolved tickets.	`ratio`	`percent`	`ticket_resolved`
`workflow_resolved_tickets`	Resolved tickets completed through workflow automation.	`count`	`count`	`ticket_resolved`
`workflow_resolution_rate`	Workflow-resolved tickets divided by resolved tickets.	`ratio`	`percent`	`ticket_resolved`
`ai_actions`	Tracked customer-facing actions completed by AI in the period.	`count`	`count`	`action_executed`
`human_actions`	Tracked customer-facing actions completed by humans in the period.	`count`	`count`	`action_executed`
`action_automation_rate`	AI actions divided by total tracked actions; not an average of per-ticket automation percentages.	`ratio`	`percent`	`action_executed`
`time_saved`	Estimated human time saved by AI actions using workspace action-time assumptions.	`sum`	`duration-seconds`	`action_executed`
`money_saved`	Estimated EUR saved using time savings and the workspace hourly rate.	`sum`	`currency-eur`	`action_executed`
`ai_spend`	Estimated EUR from recorded AI credits at the fallback rate; see the run-date exception above.	`sum`	`currency-eur`	`action_executed`
`ai_reopen_rate`	AI-resolved tickets that reopened divided by AI-resolved tickets.	`ratio`	`percent`	`ticket_resolved`
`ai_csat`	Average submitted CSAT score for AI-involved tickets, on the 1-5 scale.	`average`	`decimal`	`survey_submitted`
`ai_suggestion_used_rate`	AI draft suggestions used divided by AI suggestions offered, on tickets resolved in the period.	`ratio`	`percent`	`ticket_resolved`

Troubleshooting

Response	What to check
`401`	Supply a valid API key.
`403`	Grant `analytics:read`, assign the key to an agent, and check that agent’s dashboard permissions for queries.
`400`	Check clause syntax, metric IDs, timezone, and metric/grouping compatibility. Keep ranges within 90 calendar days, or 31 days for hourly reports. Oversized ranges return `VALIDATION_ERROR` with `details.requested_days`, `details.max_days`, and `details.timezone`. Split the query into non-overlapping `SINCE`/`UNTIL` windows; both dates are inclusive, so start the next window on the following day. Reduce metrics or comparisons when the query exceeds its execution budget.
`429`	Wait for the `Retry-After` header before retrying.

Date-range validation, an estimated query-cost check, and returned row/point limits do not guarantee a universal execution deadline or a cap on every result cell or underlying database operation. LIMIT trims returned rows or points; it is not pagination or a guarantee of less database work. Split large reporting jobs into smaller date windows. Historical completeness and freshness depend on the available reporting data; a successful response does not certify either. If a valid small query fails or totals look incomplete, contact support with the response request_id, timezone, and a redacted query. Never share your API key.

​Access and limits

​Discover metrics

​Query report data

​Query language

​Query examples

​Daily ticket volume

​Yesterday’s ticket KPI

​New tickets by channel

​First response durations

​CSAT score and sample size

​Automation savings and spend

​Filtered team workload

​Current customer-waiting snapshot

​Read results

​Metric reference

​Volume and workload

​Response and resolution

​Quality and satisfaction

​AI and automation

​Troubleshooting