Report APIs
Overview
Report APIs return pre-aggregated analytics for a workspace. The portal Dashboard is built on them.
| Query | What it returns | One row per |
|---|---|---|
convsReport | Conversation volume, response times and ratings | Channel, day and hour |
agentsReport | The same metrics per human agent | Agent, Channel and day |
convStagesReport | The same metrics per lifecycle stage | Lifecycle stage, Channel and day |
convTagsReport | The same metrics per conversation tag | Tag, Channel and day |
messageReport | Message counts by delivery status | UTC hour |
messageReportToday | Live message counts for the current UTC day | One object |
Broadcast usage has its own daily report on the Broadcasts page: Broadcast Report API.
Access: all report APIs need the MANAGE_CONVS permission (Owner, Admin, Manager). Workspace API keys can call them. Agent API keys are rejected because their Agent+ ceiling doesn’t include MANAGE_CONVS (see API Keys).
How conversation reports are built
convsReport, agentsReport, convStagesReport and convTagsReport are updated when a conversation ends: an agent or AI assistant ends it, or it is closed automatically after the workspace conversation TTL. Open conversations are not counted until they end. When a conversation ends, it is added to:
- the
convsReportrow for its Channel and the hour it ended - the
agentsReportrow of the last human agent assigned to it. Conversations with no human agent, or whose agent was deleted, are skipped. - the
convStagesReportrow of the lifecycle stage it has when it ends. Conversations without a stage are skipped. - one
convTagsReportrow for each tag it has when it ends. A conversation with three tags counts in three rows.
Days and hours are calendar buckets of the server clock, which runs in UTC. A row exists only when at least one conversation ended in that bucket, so there are no zero rows.
Date range. startDate and endDate are inclusive and are compared to each row’s createdAt, the moment the row was first written (when the first conversation of that bucket ended). They are not rounded. To cover whole UTC days, send startDate as T00:00:00.000Z of the first day and endDate as T23:59:59.999Z of the last day. Rows come back newest first and are not paginated.
Metrics. These fields mean the same thing in all four reports:
| Field | Type | Description |
|---|---|---|
conversationCount | number | Conversations that ended in this bucket. |
agentMessagesCount | number | Business-side messages in those conversations: messages from agents, AI assistants and automated replies. Every message of each conversation is counted, not only the ones sent during the bucket. Internal notes are excluded. |
clientMessageCount | number | Messages the client sent in those conversations, counted over the whole conversation. |
avgFirstResponseTime | number | Average first response time in seconds: the time from the client's first message to the first business-side message, rounded to whole seconds (at least 1). Only conversations where the client wrote before the first reply are included. |
firstResponseConversationCount | number | Number of conversations included in |
avgConversationTime | number | Average conversation duration in seconds, from when the conversation was created to when it ended, across all |
newClientConvCount | number | Conversations that were the client's first conversation in the workspace. Can be |
responseRate | number | Percentage (0-100) of conversations that received a client rating: rated conversations / |
averageRating | number | Average rating (1-5) of the rated conversations. |
csat | number | Percentage (0-100) of rated conversations rated 4 or 5. |
createdAt | DateTime | When the row was first written. |
Combining rows. Counts can be summed across rows. Averages must be weighted when you merge rows:
avgFirstResponseTime: weight byfirstResponseConversationCount.avgConversationTime: weight byconversationCount.averageRating: weight by the number of rated conversations,responseRate x conversationCount / 100.csat: recompute from the positive ratings,csat x rated conversations / 100, over the total rated conversations.
How message reports are built
messageReport returns one row per workspace and UTC hour. A background job runs every hour at minute 5 (UTC) and writes the hour that just closed, for every workspace with at least one active Channel. Hours with no messages get a row with zero counts. If a run is missed, hours from the last 12 hours that have no row yet are filled in on the next run. A row is not rewritten after its hour has been processed.
totalCountcounts every message created in the hour, both from clients and from the business side. Internal notes are excluded.- The status counts (
sentCount,deliveredCount,readCount,failedCount,pendingCount,playedCount) use each message’s latest status when the row was written. A message that was delivered and then read counts only as read. Status changes after that are not reflected. - Client messages have no delivery status, so they count only toward
totalCount.totalCountminus the six status counts gives the number of messages without a status.
messageReportToday uses the same rules but counts live from UTC midnight, including the hour still in progress, with statuses as they are at query time. To build a daily series without counting an hour twice, use messageReport up to the end of yesterday (endDate = today’s UTC midnight minus 1 ms) and add messageReportToday for today.
Conversations Report API
Get conversation metrics broken down by Channel and by the hour of the day the conversations ended. Each node covers one Channel, one UTC day and one hour, and holds every conversation that ended in that hour. Group nodes by the UTC date of createdAt to get daily totals.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Only return rows for this Channel (integration) ID. Omit it to include all Channels. |
startDate | DateTime | Required. Start of the range (inclusive), compared to each row's |
endDate | DateTime | Required. End of the range (inclusive), compared to each row's |
Report fields
Each node in nodes has these fields. See How conversation reports are built for how they are calculated.
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The report row ID. |
integrationId | string | The Channel (integration) ID of the conversations. |
hour | number | Hour of the day (0-23, UTC) in which the conversations ended. The day is the UTC date of |
conversationCount | number | Conversations that ended in this bucket. |
agentMessagesCount | number | Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded. |
clientMessageCount | number | Messages the client sent in those conversations, counted over the whole conversation. |
avgFirstResponseTime | number | Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. |
firstResponseConversationCount | number | Conversations included in |
avgConversationTime | number | Average seconds from conversation creation to conversation end. |
newClientConvCount | number | Conversations that were the client's first conversation in the workspace. Can be |
responseRate | number | Percentage (0-100) of conversations that received a client rating. |
averageRating | number | Average rating (1-5) of the rated conversations. |
csat | number | Percentage (0-100) of rated conversations rated 4 or 5. |
createdAt | DateTime | When the row was first written, the end time of the first conversation in this hour. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery convsReport($input: ConvsReportInput!) {
convsReport(input: $input) {
nodes {
id
integrationId
hour
conversationCount
agentMessagesCount
clientMessageCount
avgFirstResponseTime
firstResponseConversationCount
avgConversationTime
newClientConvCount
responseRate
averageRating
csat
createdAt
}
}
}
input ConvsReportInput {
workspaceId: Int! # Workspace ID.
integrationId: ID # Filter by Channel (integration) ID.
startDate: DateTime! # Range start (inclusive), compared to the row createdAt.
endDate: DateTime! # Range end (inclusive), compared to the row createdAt.
}The query above returns JSON structured like this:
{
"data": {
"convsReport": {
"nodes": [
{
"id": "convreport_456",
"integrationId": "integration_123",
"hour": 14,
"conversationCount": 8,
"agentMessagesCount": 46,
"clientMessageCount": 39,
"avgFirstResponseTime": 95,
"firstResponseConversationCount": 7,
"avgConversationTime": 1830,
"newClientConvCount": 3,
"responseRate": 50,
"averageRating": 4.25,
"csat": 75,
"createdAt": "2026-10-17T14:03:12.000Z"
},
{
"id": "convreport_123",
"integrationId": "integration_123",
"hour": 9,
"conversationCount": 5,
"agentMessagesCount": 21,
"clientMessageCount": 18,
"avgFirstResponseTime": 140,
"firstResponseConversationCount": 5,
"avgConversationTime": 2400,
"newClientConvCount": 1,
"responseRate": 20,
"averageRating": 3,
"csat": 0,
"createdAt": "2026-10-17T09:12:40.000Z"
}
]
}
}
}Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row. In the example, four of the eight conversations that ended between 14:00 and 15:00 were rated (responseRate 50) with 5, 5, 4 and 3 (averageRating 4.25, csat 75).
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"convsReport","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","startDate":"2026-10-17T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query convsReport($input: ConvsReportInput!) {\n convsReport(input: $input) {\n nodes {\n id\n integrationId\n hour\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'Agents Report API
Get conversation metrics per human agent, per Channel and per UTC day. A conversation is attributed to the last human (non-AI) agent in its assignment history, or to its current assignee when the history has none. Conversations handled only by AI assistants are not counted here.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
agentId | string | Only return rows for this agent ID. Ignored when |
agentIds | string[] | Only return rows for any of these agent IDs. Takes precedence over |
integrationId | string | Only return rows for this Channel (integration) ID. Omit it to include all Channels. |
startDate | DateTime | Required. Start of the range (inclusive), compared to each row's |
endDate | DateTime | Required. End of the range (inclusive), compared to each row's |
Report fields
Each node in nodes has these fields. See How conversation reports are built for how they are calculated.
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The report row ID. |
agentId | string | The agent the conversations are attributed to. |
integrationId | string | The Channel (integration) ID of the conversations. Can be |
conversationCount | number | Conversations that ended in this bucket. |
agentMessagesCount | number | Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded. |
clientMessageCount | number | Messages the client sent in those conversations, counted over the whole conversation. |
avgFirstResponseTime | number | Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. |
firstResponseConversationCount | number | Conversations included in |
avgConversationTime | number | Average seconds from conversation creation to conversation end. |
newClientConvCount | number | Conversations that were the client's first conversation in the workspace. Can be |
responseRate | number | Percentage (0-100) of conversations that received a client rating. |
averageRating | number | Average rating (1-5) of the rated conversations. |
csat | number | Percentage (0-100) of rated conversations rated 4 or 5. |
createdAt | DateTime | When the row was first written, the end time of the agent's first conversation that day. The day of the row is the UTC date of this value. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery agentsReport($input: AgentsReportInput!) {
agentsReport(input: $input) {
nodes {
id
agentId
integrationId
conversationCount
agentMessagesCount
clientMessageCount
avgFirstResponseTime
firstResponseConversationCount
avgConversationTime
newClientConvCount
responseRate
averageRating
csat
createdAt
}
}
}
input AgentsReportInput {
workspaceId: Int! # Workspace ID.
agentId: ID # Filter by one agent ID.
agentIds: [ID!] # Filter by any of these agent IDs. Wins over agentId when non-empty.
integrationId: ID # Filter by Channel (integration) ID.
startDate: DateTime! # Range start (inclusive), compared to the row createdAt.
endDate: DateTime! # Range end (inclusive), compared to the row createdAt.
}The query above returns JSON structured like this:
{
"data": {
"agentsReport": {
"nodes": [
{
"id": "agentreport_789",
"agentId": "agent_123",
"integrationId": "integration_123",
"conversationCount": 10,
"agentMessagesCount": 74,
"clientMessageCount": 61,
"avgFirstResponseTime": 82,
"firstResponseConversationCount": 9,
"avgConversationTime": 1520,
"newClientConvCount": 4,
"responseRate": 40,
"averageRating": 4,
"csat": 75,
"createdAt": "2026-10-17T08:41:05.000Z"
},
{
"id": "agentreport_456",
"agentId": "agent_456",
"integrationId": "integration_123",
"conversationCount": 6,
"agentMessagesCount": 30,
"clientMessageCount": 28,
"avgFirstResponseTime": 210,
"firstResponseConversationCount": 6,
"avgConversationTime": 2950,
"newClientConvCount": 2,
"responseRate": 0,
"averageRating": 0,
"csat": 0,
"createdAt": "2026-10-16T10:15:30.000Z"
}
]
}
}
}Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row.
agentMessagesCount counts all business-side messages in the attributed conversations, including messages from other agents or AI assistants in the same conversation, not only the messages this agent sent.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"agentsReport","variables":{"input":{"workspaceId":12,"agentIds":["agent_123","agent_456"],"startDate":"2026-10-16T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query agentsReport($input: AgentsReportInput!) {\n agentsReport(input: $input) {\n nodes {\n id\n agentId\n integrationId\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'Conversation Stages Report API
Get conversation metrics per lifecycle stage, per Channel and per UTC day. A conversation counts toward the stage it has when it ends. Conversations without a lifecycle stage are not counted.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Only return rows for this Channel (integration) ID. Omit it to include all Channels. |
stage | string | Only return rows for this lifecycle stage name (exact match). Ignored when |
stages | string[] | Only return rows for any of these lifecycle stage names. Takes precedence over |
startDate | DateTime | Required. Start of the range (inclusive), compared to each row's |
endDate | DateTime | Required. End of the range (inclusive), compared to each row's |
Report fields
Each node in nodes has these fields. See How conversation reports are built for how they are calculated.
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The report row ID. |
stage | string | The lifecycle stage name. |
integrationId | string | The Channel (integration) ID of the conversations. |
conversationCount | number | Conversations that ended in this bucket. |
agentMessagesCount | number | Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded. |
clientMessageCount | number | Messages the client sent in those conversations, counted over the whole conversation. |
avgFirstResponseTime | number | Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. |
firstResponseConversationCount | number | Conversations included in |
avgConversationTime | number | Average seconds from conversation creation to conversation end. |
newClientConvCount | number | Conversations that were the client's first conversation in the workspace. Can be |
responseRate | number | Percentage (0-100) of conversations that received a client rating. |
averageRating | number | Average rating (1-5) of the rated conversations. |
csat | number | Percentage (0-100) of rated conversations rated 4 or 5. |
createdAt | DateTime | When the row was first written, the end time of the first conversation in this stage that day. The day of the row is the UTC date of this value. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery convStagesReport($input: ConvStagesReportInput!) {
convStagesReport(input: $input) {
nodes {
id
stage
integrationId
conversationCount
agentMessagesCount
clientMessageCount
avgFirstResponseTime
firstResponseConversationCount
avgConversationTime
newClientConvCount
responseRate
averageRating
csat
createdAt
}
}
}
input ConvStagesReportInput {
workspaceId: Int! # Workspace ID.
integrationId: ID # Filter by Channel (integration) ID.
stage: String # Filter by one lifecycle stage name.
stages: [String!] # Filter by any of these stage names. Wins over stage when non-empty.
startDate: DateTime! # Range start (inclusive), compared to the row createdAt.
endDate: DateTime! # Range end (inclusive), compared to the row createdAt.
}The query above returns JSON structured like this:
{
"data": {
"convStagesReport": {
"nodes": [
{
"id": "stagereport_456",
"stage": "Won",
"integrationId": "integration_123",
"conversationCount": 4,
"agentMessagesCount": 22,
"clientMessageCount": 19,
"avgFirstResponseTime": 60,
"firstResponseConversationCount": 4,
"avgConversationTime": 3600,
"newClientConvCount": 1,
"responseRate": 50,
"averageRating": 4.5,
"csat": 100,
"createdAt": "2026-10-17T11:20:00.000Z"
},
{
"id": "stagereport_123",
"stage": "Qualified",
"integrationId": "integration_123",
"conversationCount": 7,
"agentMessagesCount": 35,
"clientMessageCount": 33,
"avgFirstResponseTime": 120,
"firstResponseConversationCount": 6,
"avgConversationTime": 2700,
"newClientConvCount": 5,
"responseRate": 0,
"averageRating": 0,
"csat": 0,
"createdAt": "2026-10-17T08:05:45.000Z"
}
]
}
}
}Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row. Moving a conversation to another stage after it ended doesn’t change rows that were already written.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"convStagesReport","variables":{"input":{"workspaceId":12,"stages":["Qualified","Won"],"startDate":"2026-10-17T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query convStagesReport($input: ConvStagesReportInput!) {\n convStagesReport(input: $input) {\n nodes {\n id\n stage\n integrationId\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'Conversation Tags Report API
Get conversation metrics per conversation tag, per Channel and per UTC day. When a conversation ends, it counts once toward each tag it has, so the same conversation can appear in several rows. Conversations without tags are not counted.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | Only return rows for this Channel (integration) ID. Omit it to include all Channels. |
tag | string | Only return rows for this tag name (exact match). Ignored when |
tags | string[] | Only return rows for any of these tag names. Takes precedence over |
startDate | DateTime | Required. Start of the range (inclusive), compared to each row's |
endDate | DateTime | Required. End of the range (inclusive), compared to each row's |
Report fields
Each node in nodes has these fields. See How conversation reports are built for how they are calculated.
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The report row ID. |
tag | string | The tag name. |
integrationId | string | The Channel (integration) ID of the conversations. |
conversationCount | number | Conversations that ended in this bucket. |
agentMessagesCount | number | Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded. |
clientMessageCount | number | Messages the client sent in those conversations, counted over the whole conversation. |
avgFirstResponseTime | number | Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. |
firstResponseConversationCount | number | Conversations included in |
avgConversationTime | number | Average seconds from conversation creation to conversation end. |
newClientConvCount | number | Conversations that were the client's first conversation in the workspace. Can be |
responseRate | number | Percentage (0-100) of conversations that received a client rating. |
averageRating | number | Average rating (1-5) of the rated conversations. |
csat | number | Percentage (0-100) of rated conversations rated 4 or 5. |
createdAt | DateTime | When the row was first written, the end time of the first conversation with this tag that day. The day of the row is the UTC date of this value. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery convTagsReport($input: ConvTagsReportInput!) {
convTagsReport(input: $input) {
nodes {
id
tag
integrationId
conversationCount
agentMessagesCount
clientMessageCount
avgFirstResponseTime
firstResponseConversationCount
avgConversationTime
newClientConvCount
responseRate
averageRating
csat
createdAt
}
}
}
input ConvTagsReportInput {
workspaceId: Int! # Workspace ID.
integrationId: ID # Filter by Channel (integration) ID.
tag: String # Filter by one tag name.
tags: [String!] # Filter by any of these tag names. Wins over tag when non-empty.
startDate: DateTime! # Range start (inclusive), compared to the row createdAt.
endDate: DateTime! # Range end (inclusive), compared to the row createdAt.
}The query above returns JSON structured like this:
{
"data": {
"convTagsReport": {
"nodes": [
{
"id": "tagreport_456",
"tag": "refund",
"integrationId": "integration_123",
"conversationCount": 4,
"agentMessagesCount": 18,
"clientMessageCount": 20,
"avgFirstResponseTime": 150,
"firstResponseConversationCount": 4,
"avgConversationTime": 2100,
"newClientConvCount": 0,
"responseRate": 25,
"averageRating": 2,
"csat": 0,
"createdAt": "2026-10-17T12:47:10.000Z"
},
{
"id": "tagreport_123",
"tag": "billing",
"integrationId": "integration_123",
"conversationCount": 8,
"agentMessagesCount": 40,
"clientMessageCount": 37,
"avgFirstResponseTime": 75,
"firstResponseConversationCount": 8,
"avgConversationTime": 1980,
"newClientConvCount": 2,
"responseRate": 50,
"averageRating": 4,
"csat": 75,
"createdAt": "2026-10-17T09:02:33.000Z"
}
]
}
}
}Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row. Because a conversation counts toward every tag it has, adding up conversationCount across tags can be higher than the number of conversations that ended.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"convTagsReport","variables":{"input":{"workspaceId":12,"tags":["billing","refund"],"startDate":"2026-10-17T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query convTagsReport($input: ConvTagsReportInput!) {\n convTagsReport(input: $input) {\n nodes {\n id\n tag\n integrationId\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'Hourly Message Report API
Get message counts per UTC hour for a workspace. Each node covers one hour, starting at reportHour. Rows are written by an hourly job, so the hour in progress and the hour that closed less than about 5 minutes ago are not included yet. Use Today’s Message Report API for live numbers.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
startDate | DateTime | Required. Start of the range (inclusive). Rounded down to the start of its UTC hour. |
endDate | DateTime | Required. End of the range (inclusive). Rounded down to the start of its UTC hour, and that hour is included. |
Report fields
Each node in nodes has these fields. See How message reports are built.
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The report row ID. |
reportHour | DateTime | UTC start of the hour this row covers. The row counts messages created from |
totalCount | number | All messages created in the hour, from clients and from the business side. Internal notes are excluded. |
sentCount | number | Messages whose status was |
deliveredCount | number | Messages whose status was |
readCount | number | Messages whose status was |
failedCount | number | Messages whose status was |
pendingCount | number | Messages whose status was |
playedCount | number | Messages whose status was |
createdAt | DateTime | When the row was first written, usually about 5 minutes after the hour closed. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery messageReport($input: MessageReportInput!) {
messageReport(input: $input) {
nodes {
id
reportHour
totalCount
sentCount
deliveredCount
readCount
failedCount
pendingCount
playedCount
createdAt
}
}
}
input MessageReportInput {
workspaceId: Int! # Workspace ID.
startDate: DateTime! # Range start (inclusive), rounded down to the UTC hour.
endDate: DateTime! # Range end (inclusive), rounded down to the UTC hour.
}The query above returns JSON structured like this:
{
"data": {
"messageReport": {
"nodes": [
{
"id": "messagereport_456",
"reportHour": "2026-10-16T23:00:00.000Z",
"totalCount": 42,
"sentCount": 3,
"deliveredCount": 10,
"readCount": 12,
"failedCount": 1,
"pendingCount": 0,
"playedCount": 1,
"createdAt": "2026-10-17T00:05:03.000Z"
},
{
"id": "messagereport_123",
"reportHour": "2026-10-16T22:00:00.000Z",
"totalCount": 0,
"sentCount": 0,
"deliveredCount": 0,
"readCount": 0,
"failedCount": 0,
"pendingCount": 0,
"playedCount": 0,
"createdAt": "2026-10-16T23:05:02.000Z"
}
]
}
}
}Rows are sorted by reportHour, newest first, and are not paginated. The example range returns up to 24 rows, from 00:00 to 23:00 UTC; two are shown. In the 23:00 row, 27 messages have a status and the other 15 are client messages, which have no delivery status.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"messageReport","variables":{"input":{"workspaceId":12,"startDate":"2026-10-16T00:00:00.000Z","endDate":"2026-10-16T23:59:59.999Z"}},"query":"query messageReport($input: MessageReportInput!) {\n messageReport(input: $input) {\n nodes {\n id\n reportHour\n totalCount\n sentCount\n deliveredCount\n readCount\n failedCount\n pendingCount\n playedCount\n createdAt\n }\n }\n}"}'Today’s Message Report API
Get live message counts for the current UTC day, from 00:00 UTC up to now, including the hour still in progress. Counts are computed at query time, so statuses are current.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
Report fields
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
reportDate | DateTime | UTC midnight that starts the current day. |
totalCount | number | All messages created today, from clients and from the business side. Internal notes are excluded. |
sentCount | number | Messages whose current status is |
deliveredCount | number | Messages whose current status is |
readCount | number | Messages whose current status is |
failedCount | number | Messages whose current status is |
pendingCount | number | Messages whose current status is |
playedCount | number | Messages whose current status is |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery messageReportToday($input: MessageReportTodayInput!) {
messageReportToday(input: $input) {
workspaceId
reportDate
totalCount
sentCount
deliveredCount
readCount
failedCount
pendingCount
playedCount
}
}
input MessageReportTodayInput {
workspaceId: Int! # Workspace ID.
}The query above returns JSON structured like this:
{
"data": {
"messageReportToday": {
"workspaceId": 12,
"reportDate": "2026-10-17T00:00:00.000Z",
"totalCount": 318,
"sentCount": 12,
"deliveredCount": 64,
"readCount": 88,
"failedCount": 4,
"pendingCount": 2,
"playedCount": 3
}
}
}Client messages have no delivery status, so they count only toward totalCount. In the example, 173 messages have a status and 145 are client messages. To chart the last few days without counting an hour twice, combine this result with the Hourly Message Report API up to the end of yesterday.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"messageReportToday","variables":{"input":{"workspaceId":12}},"query":"query messageReportToday($input: MessageReportTodayInput!) {\n messageReportToday(input: $input) {\n workspaceId\n reportDate\n totalCount\n sentCount\n deliveredCount\n readCount\n failedCount\n pendingCount\n playedCount\n }\n}"}'