Scopes and endpoints: reports, CSAT, SLA

Last updated: 11 November 2026 · 6 min read

Steps

1. 1

   How to read this article

   • Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
   • Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
   • Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
   • Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
   • "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
   • When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
   • Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
2. 2

   Read reports (reports:read)

   Reads totals: conversation and message counts, first response and resolution times, totals per agent, inbox, label, team and channel, live counts, AI agent and bot metrics, reporting events. No customer personal data, so it is low risk. This is the main scope for a BI tool.

   • Risk: low.
   • Review: goes through review; low risk scopes are looked at quickly.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/conversations/{conversation_id}/reporting_events: List a conversation's reporting events
   • GET /v1/live_reports/conversation_metrics: Get live conversation counts
   • GET /v1/live_reports/grouped_conversation_metrics: Get live conversation counts by agent or team
   • GET /v1/reporting_events: List reporting events
   • GET /v1/reports: Get a report time series
   • GET /v1/reports/agents: Get report totals per agent
   • GET /v1/reports/bot_metrics: Get AI agent and bot metrics
   • GET /v1/reports/bot_summary: Get AI agent and bot totals
   • GET /v1/reports/conversation_traffic: Get conversation traffic by hour and weekday
   • GET /v1/reports/conversations: Get open conversation counts per agent
   • GET /v1/reports/conversations_summary: Get a conversation summary
   • GET /v1/reports/first_response_time_distribution: Get the first response time distribution
   • GET /v1/reports/inbox_label_matrix: Get conversation counts by inbox and label
   • GET /v1/reports/inboxes: Get report totals per inbox
   • GET /v1/reports/labels: Get report totals per label
   • GET /v1/reports/outgoing_messages_count: Get outgoing message counts
   • GET /v1/reports/summary: Get report totals
   • GET /v1/reports/teams: Get report totals per team
   • GET /v1/summary_reports/agent: Get the summary report per agent
   • GET /v1/summary_reports/channel: Get the summary report per channel
   • GET /v1/summary_reports/inbox: Get the summary report per inbox
   • GET /v1/summary_reports/label: Get the summary report per label
   • GET /v1/summary_reports/team: Get the summary report per team

   Example:

   curl "https://api.clomni.ai/v1/reports?metric=conversations_count&type=account&since=1793491200&until=1794096000&group_by=day&timezone_offset=4" \
     -H "Authorization: Bearer clomni_pat_xxx"

   curl "https://api.clomni.ai/v1/live_reports/conversation_metrics" \
     -H "Authorization: Bearer clomni_pat_xxx"

3. 3

   Read CSAT responses (csat:read)

   Reads customer satisfaction (CSAT) ratings, comments and the totals. Comments hold the customer's own words, so it is medium risk.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/csat_survey_responses: List CSAT responses
   • GET /v1/csat_survey_responses/metrics: Get CSAT totals

   Example:

   curl "https://api.clomni.ai/v1/csat_survey_responses?since=1793491200&until=1794096000&page=1" \
     -H "Authorization: Bearer clomni_pat_xxx"

   curl "https://api.clomni.ai/v1/csat_survey_responses/metrics" \
     -H "Authorization: Bearer clomni_pat_xxx"

4. 4

   Read SLA (sla:read)

   Reads SLA policies and the SLA results per conversation, breaches included.

   • Risk: low.
   • Review: goes through review; low risk scopes are looked at quickly.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/applied_slas: List SLA results per conversation
   • GET /v1/applied_slas/metrics: Get SLA totals
   • GET /v1/sla_policies: List SLA policies
   • GET /v1/sla_policies/{sla_policy_id}: Get an SLA policy

   Example:

   curl "https://api.clomni.ai/v1/sla_policies" \
     -H "Authorization: Bearer clomni_pat_xxx"

   curl "https://api.clomni.ai/v1/applied_slas" \
     -H "Authorization: Bearer clomni_pat_xxx"

5. 5

   Edit SLA policies (sla:write)

   Creates, changes and deletes SLA policies: first response, next response and resolution times, and whether only business hours count.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: sla:read.

   Endpoints:

   • POST /v1/sla_policies: Create an SLA policy
   • PATCH /v1/sla_policies/{sla_policy_id}: Update an SLA policy
   • DELETE /v1/sla_policies/{sla_policy_id}: Delete an SLA policy

   Example:

   curl -X POST "https://api.clomni.ai/v1/sla_policies" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"name": "Standart", "first_response_time_threshold": 900, "resolution_time_threshold": 28800, "only_during_business_hours": true}'

6. 6

   Related articles

   • Which scopes you need: scopes and endpoints by what you want to do
   • Recipe: export your history and keep it in sync
   • Using Developer API endpoints: examples, pagination, idempotency