Insights and credits
The key figures of an agent per day and per channel, and the AI credits it can still spend in the current period.
Key figures
GET/v1/agents/{agent_id}/insights
Conversations, messages, leads, topics and countries per day, at most 366 days.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
start_date | stringquery | First day, as YYYY-MM-DD (UTC). |
end_date | stringquery | Last day, inclusive, as YYYY-MM-DD (UTC). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
daily | array of objects | One row per day with activity. |
daily[].conversations | integer | Conversations with activity that day. |
daily[].date | string | The day (UTC). |
daily[].replies | integer | Answers of the agent and of your team. |
daily[].visitor_messages | integer | Messages from visitors. |
end_date | string | Last day of the range, inclusive. |
start_date | string | First day of the range. |
timezone | string | Time zone of the days, always UTC. |
totals | object | Sums for the whole range. |
totals.conversations | integer | Conversations with activity in the range. |
totals.leads | integer | Leads collected in the range. |
totals.replies | integer | Answers of the agent and of your team. |
totals.visitor_messages | integer | Messages from visitors. |
platforms | array of objects | The same figures per channel. |
platforms[].conversations | integer | Conversations on this channel. |
platforms[].platform | string | The channel, e.g. website, whatsapp or api. |
platforms[].replies | integer | Answers on this channel. |
platforms[].visitor_messages | integer | Visitor messages on this channel. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/insights" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/insights",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/insights", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"daily": [
{
"conversations": 16,
"date": "2026-11-10",
"replies": 20,
"visitor_messages": 18
}
],
"end_date": "2026-11-10",
"platforms": [
{
"conversations": 13,
"platform": "api",
"replies": 17,
"visitor_messages": 17
}
],
"start_date": "2026-10-12",
"timezone": "UTC",
"totals": {
"conversations": 16,
"leads": 3,
"replies": 20,
"visitor_messages": 18
}
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
AI credits and usage
GET/v1/agents/{agent_id}/credits
Balance, plan allowance and price per answer.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
available | integer or null | What the agent can still spend in this period. |
object | string | Always credits. |
plan_allowance | integer or null | Credits (or answers) of the plan in the current period. |
plan_name | string or null | Name of the agent's plan. |
unit | string | credits, or answers for an agent that still counts answers. One of credits, answers. |
answer_level | string | The agent's intelligence level: standard (Ultimo Core), advanced (Ultimo Pro) or expert (Ultimo Max). |
answer_price | integer | Credits one answer costs at this level: 1, 4 or 8. |
balance | integer | Credits left in total, plan and extra credits together. |
extra_remaining | integer | Extra credits bought on top of the plan that are left. |
extra_total | integer | Extra credits bought on top of the plan. |
mode | string | on when the agent pays with AI credits, off when it still counts answers. |
period_end | string | End of the current billing period, in UTC. |
period_start | string | Start of the current billing period, in UTC. |
plan_remaining | integer | Plan credits left in this period. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/credits" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/credits",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/credits", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"answer_level": "standard",
"answer_price": 1,
"available": 9100,
"balance": 9100,
"extra_remaining": 0,
"extra_total": 0,
"mode": "on",
"object": "credits",
"period_end": "2026-12-01T00:00:00",
"period_start": "2026-11-01T00:00:00",
"plan_allowance": 10000,
"plan_name": "Ultimo",
"plan_remaining": 9100,
"unit": "credits"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.