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.

2 min read Updated

Key figures

GET/v1/agents/{agent_id}/insights

Permission reports:read

Conversations, messages, leads, topics and countries per day, at most 366 days.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
start_datestringqueryFirst day, as YYYY-MM-DD (UTC).
end_datestringqueryLast day, inclusive, as YYYY-MM-DD (UTC).

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
dailyarray of objectsOne row per day with activity.
daily[].conversationsintegerConversations with activity that day.
daily[].datestringThe day (UTC).
daily[].repliesintegerAnswers of the agent and of your team.
daily[].visitor_messagesintegerMessages from visitors.
end_datestringLast day of the range, inclusive.
start_datestringFirst day of the range.
timezonestringTime zone of the days, always UTC.
totalsobjectSums for the whole range.
totals.conversationsintegerConversations with activity in the range.
totals.leadsintegerLeads collected in the range.
totals.repliesintegerAnswers of the agent and of your team.
totals.visitor_messagesintegerMessages from visitors.
platformsarray of objectsThe same figures per channel.
platforms[].conversationsintegerConversations on this channel.
platforms[].platformstringThe channel, e.g. website, whatsapp or api.
platforms[].repliesintegerAnswers on this channel.
platforms[].visitor_messagesintegerVisitor 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"

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

Permission credits:read

Balance, plan allowance and price per answer.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
availableinteger or nullWhat the agent can still spend in this period.
objectstringAlways credits.
plan_allowanceinteger or nullCredits (or answers) of the plan in the current period.
plan_namestring or nullName of the agent's plan.
unitstringcredits, or answers for an agent that still counts answers. One of credits, answers.
answer_levelstringThe agent's intelligence level: standard (Ultimo Core), advanced (Ultimo Pro) or expert (Ultimo Max).
answer_priceintegerCredits one answer costs at this level: 1, 4 or 8.
balanceintegerCredits left in total, plan and extra credits together.
extra_remainingintegerExtra credits bought on top of the plan that are left.
extra_totalintegerExtra credits bought on top of the plan.
modestringon when the agent pays with AI credits, off when it still counts answers.
period_endstringEnd of the current billing period, in UTC.
period_startstringStart of the current billing period, in UTC.
plan_remainingintegerPlan 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"

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.

Next steps