Count conversations

Count the conversations list_conversations returns for the same filters (every filter it takes, without sort), up to 10,000: capped then says at least that many match. averageMessageCount and averageDurationSeconds are their average length. groupBy also divides them, largest group first, each with its outcomes: by outcome, status, channel, agent, sentiment, tool (which Agent tools they used, and in how many a tool failed), toolError (why calls of toolName failed) or fact:<definition key> (such as the reason for contact). Use it to answer how many conversations match, or how they divide, instead of paging through the list; for volumes per day use get_report.

Scopes: any one of raiz:conversations:read, raiz:conversations:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 1 MB
CLI: arbol raiz conversations count · MCP tool: raiz_conversations_count

GET

https://api.getarbol.com/v1/raiz/conversations/count

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes raiz:conversations:read, raiz:conversations:write. Get an API key.

Query parameters

agentId
optional
string
Agent id.

pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
campaignId
optional
string
Attempts of this campaign.

pattern: ^cmp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
channelId
optional
string
Channel id.

pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
channelType
optional
string
Comma-separated channel types.

pattern: ^(voice|whatsapp|web)(,(voice|whatsapp|web))*$
contactId
optional
string
Conversations with this contact as counterpart or subject. A merged duplicate's id lists the survivor's.

pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
conversationDirection
optional
inbound
or
outbound
inbound: the contact started it; outbound: the organization did. It matches each conversation's direction (the query field direction pages the list).
handling
optional
ai
or
team
or
escalated
ai: conversations the AI takes part in (calls and web chats, and WhatsApp conversations the AI handles or answered). team: WhatsApp conversations the organization's people handle on their own. escalated: conversations the AI handed to the team (a request it could not resolve, a contact who asked for a person, or a spent budget), also once the team gave them back to the AI; the ones conversations_daily counts in escalatedCount. A trial is not one, nor a conversation that opens while the AI is still paused for the number after an earlier handoff.
worker
optional
ai
or
team
Who works the conversation now. ai: calls and web chats, open WhatsApp conversations the AI answers (assigned to it and not paused), and closed ones the AI answered. team: open WhatsApp conversations the organization's people answer (not assigned to the AI, or paused) and closed ones they answered. Unlike handling, a conversation the AI answered and then handed to people is team while open.
origin
optional
string
Comma-separated origins.

pattern: ^(inbound|manual|api|campaign|import|test)(,(inbound|manual|api|campaign|import|test))*$
outcome
optional
string
Comma-separated outcomes of the analysis.

pattern: ^(success|failure|unknown)(,(success|failure|unknown))*$
metadataReference
optional
string
Conversations whose metadata.reference is exactly this value: the reference a caller gave createConversation, to find a conversation whose answer it did not receive.

maxLength: 500 · minLength: 1
profileId
optional
string
Conversations started from this communication profile.

pattern: ^prf_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
q
optional
string
Search participant names, channel profile names, usernames, phones, emails, identity documents, visible message text, conversation ids and exact external references. Ignores accents/case and phone/document formatting. Also searches titles and summaries with Spanish stemming (quoted phrases, or and -word apply there). Attachments without stored transcription and tool payloads are not searched.

maxLength: 200 · minLength: 1
requestedBy
optional
string
Conversations started with createConversation by this token subject (exact match): a machine client reads its own requests with <client id>@clients.

maxLength: 255 · minLength: 1
startedAfter
optional
string
Started at or after this instant (RFC 3339).

format: date-time
startedBefore
optional
string
Started before this instant (RFC 3339).

format: date-time
status
optional
open
or
closed
period
optional
today
or
7d
or
30d
or
90d
or
365d
Started today or in the last 7, 30, 90 or 365 days including today, counting days in the organization's time zone as get_report does. A saved view keeps its period this way, so it moves with the calendar.
sentiment
optional
string
Comma-separated sentiments of the analysis.

pattern: ^(positive|neutral|negative)(,(positive|neutral|negative))*$
toolName
optional
string
Conversations where the Agent called this tool: its exact name, as the transcript's tool parts show it (toolName). count_conversations with groupBy=tool lists the names with how many conversations used each.

maxLength: 128 · minLength: 1
toolStatus
optional
completed
or
failed
or
denied
With toolName, a call of that tool ended this way; alone, a call of any tool did (failed: conversations where a tool failed).
factDefinition
optional
string
Conversations whose current fact of this definition (its key) is known: about the conversation, or about its contact for a contact definition. With factValue, equal to that value.

pattern: ^[a-z][a-z0-9_]{0,63}$
factValue
optional
string
With factDefinition: an option's key or label, a text (ignoring case), a number, a date (YYYY-MM-DD) or true/false.

maxLength: 500 · minLength: 1
assessment
optional
failed
or
passed
The conversation's yes/no assessments: failed, at least one answered no; passed, at least one answered and every answered one yes.
toReview
optional
boolean
true: conversations to review, as get_report counts them in toReviewCount: the analysis says the request was not resolved, or the AI handed the conversation to the team. false: the others.
messagesMin
optional
integer
At least this many messages.

minimum: 0
messagesMax
optional
integer
At most this many messages.

minimum: 0
durationMin
optional
integer
Calls of at least this many seconds.

minimum: 0
durationMax
optional
integer
Calls of at most this many seconds.

minimum: 0
groupBy
optional
string
outcome, status, channel (type), agent, sentiment, tool (each Agent tool and the conversations that used it; null for those that used none), toolError (failed calls, of toolName when given, by error) or fact:<definition key> (the current value of that definition, such as the reason for contact).

pattern: ^(outcome|status|channel|agent|sentiment|tool|toolError|fact:[a-z][a-z0-9_]{0,63})$

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- capped
  boolean
  required
  True when the count reached 10000: at least that many match.
- count
  integer
  required
  How many match the filters, counted up to 10000.
  
  maximum: 10000 · minimum: 0
- averageDurationSeconds
  number | null
  required
  The average duration of the calls among them, in seconds; null when none has one.
  
  minimum: 0
- averageMessageCount
  number | null
  required
  Their average number of messages; null when there are none.
  
  minimum: 0
- groups
  array | null
  required
  With groupBy: the counted conversations by group, largest first, at most 100. A conversation counts once per group; with tool, once in each tool it used.
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}