Support Metrics

The Support Metrics endpoint returns the same numbers as the Analytics → Support tab in the dashboard, so you can take them to a BI tool, a spreadsheet, or your own dashboard. The calculation happens once, inside SquadOS: the screen and the API read the same definition, so the numbers match.

The endpoint requires the Authorization: Bearer pk_... header. The organization is always the token’s owner; no parameter selects another one.

Base URL: https://api.squados.io/v1

See Authentication to get your key, and Errors for the code reference.

How the numbers are counted

Only customer conversations count. The team’s internal conversations are left out.
A conversation counts when the customer sent a message within the period.
With AI counts conversations an agent replied to in the period; with a person, those with a message from a team member in the period. Assigning the conversation without replying does not count. A conversation can count in both.
First response uses first-human-response cycles completed in the period. Times count only the inbox schedule’s service hours and come as p50 (half of the responses were sent within this time) and p95 (95% were sent within this time).
The queue (first_response_sla.queue) is the current situation and does not depend on the period.
The from and to dates are interpreted in the organization’s time zone and include both days.
Times are in seconds. When there is no basis for a value (no responses, no ratings), percentages, times, and averages come as null, never 0.

`GET /metrics/support`

Query parameters

Name	Type	Required	Description
`from`	date (`YYYY-MM-DD`)	yes	First day of the period.
`to`	date (`YYYY-MM-DD`)	yes	Last day of the period, inclusive. Must be on or after `from`.

The period can span up to 400 days (to minus from).

curl -X GET "https://api.squados.io/v1/metrics/support?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer pk_your_key_here"

Response — 200 OK

{
  "period": { "from": "2026-09-01", "to": "2026-09-30", "timezone": "America/Sao_Paulo" },
  "conversations": { "total": 1000, "ai_handled": 800, "human_handled": 600, "ai_only": 400 },
  "resolutions": { "total": 900, "by_ai": 300 },
  "first_response_sla": {
    "responded": 200,
    "within_sla": 150,
    "breached": 50,
    "compliance_pct": 75.0,
    "p50_seconds": 240,
    "p95_seconds": 3900,
    "queue": { "pending": 7, "overdue": 3, "at_risk": 2, "unassigned": 1 }
  },
  "satisfaction": { "rated": 120, "average_score": 4.35 },
  "by_inbox": [
    {
      "inbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "WhatsApp Official",
      "conversations": 700,
      "ai_handled": 500,
      "human_handled": 450,
      "sla_responded": 120,
      "sla_compliance_pct": 80.0,
      "sla_p50_seconds": 180
    }
  ],
  "attendants": [
    {
      "user_id": "9b2c1f0e-8d7a-4c3b-a1e2-5f6d7c8b9a01",
      "name": "Ana",
      "email": "[email protected]",
      "is_active_member": true,
      "responded": 80,
      "within_sla": 70,
      "breached": 10,
      "compliance_pct": 87.5,
      "p50_seconds": 200
    }
  ],
  "topics": [{ "topic": "cancellation", "conversations": 24 }],
  "contact_tags": {
    "in_period": [{ "tag": "Renewal", "contacts": 12 }],
    "all_time": [{ "tag": "VIP", "contacts": 340 }]
  }
}

Field	Description
`period`	The requested period and the organization time zone used to interpret it.
`conversations`	`total` conversations; `ai_handled` (with AI), `human_handled` (with a person), and `ai_only`.
`resolutions`	Conversations resolved in the period (`total`) and how many by AI (`by_ai`).
`first_response_sla`	First human responses completed in the period: `responded`, `within_sla`, `breached`, `compliance_pct` (one decimal place), `p50_seconds`, `p95_seconds`, and the current `queue` (`pending`, `overdue`, `at_risk`, `unassigned`).
`satisfaction`	Conversations rated in the period (`rated`) and the average score from 1 to 5 (`average_score`).
`by_inbox`	One row per inbox with conversations or responses in the period. Conversations without an inbox count in the total but do not appear here.
`attendants`	One row per attendant, most violations first. `user_id` is `null` for responses without a recognized attendant; `is_active_member` is `false` for people who left the organization.
`topics`	Up to 15 most frequent topics in the period’s conversations.
`contact_tags`	Up to 50 tags given in the period (`in_period`) and up to 50 with the total contacts for each (`all_time`).

Errors

Status	`code`	When
400	`invalid_request`	`from` or `to` missing, not in `YYYY-MM-DD` format, or not a real calendar date; `to` before `from`; period longer than 400 days.
401	`unauthorized`	Missing, invalid, or deactivated token.
500	`internal_error`	The metrics could not be computed. Try again.