Analytics and reports

Jelliu analyzes every call and text conversation your agents handle: outcome, sentiment, frustration, response latency, talk share, cost, and the fields each agent is configured to extract. The analytics API exposes those numbers as aggregates you can pull into your own BI, CRM or reporting stack.

There are four surfaces, each for a different job:

How it works

Analytics and reports are computed from the rows Jelliu stores for each call and conversation. Three consequences follow from that:

• Numbers appear after analysis. A call counts in volume as soon as it exists, but its outcome, sentiment and extracted fields only appear once post-call analysis has written them.
• Averages are over the rows that carry the measurement. A call with no sentiment score does not pull the average toward zero; it is simply not in the sample. Most responses include the sample size next to the average (sentimentCallCount, sampleSize, sentimentSampleSize) so you can tell a fleet-wide signal from a three-call one.
• Rates are recomputed on every read, never stored. Which is what lets a change in how Jelliu counts apply to your whole history at once, with no backfill — and also means a chart you drew last week over the same window may no longer match.

Authentication and access

All analytics routes are reads, so a read key is enough for every GET on this page. The exceptions:

See Authentication for how scopes map to roles.

Without an active subscription

Advanced analytics, reports and analytics exports are part of every plan, and they need the workspace to have an active subscription (active, trialing or past_due). Without one:

The refusal carries metadata.kind: "subscription_required":

{
  "error": {
    "code": "BILLING_ERROR",
    "message": "«Analítica avanzada» requiere una suscripción activa. Este espacio de trabajo no tiene un plan activo: elige uno en Ajustes → Plan para continuar. Tus datos siguen disponibles para consultar y exportar.",
    "metadata": { "tier": "none", "kind": "subscription_required" }
  }
}

Reports name Reportes personalizados and analytics exports name Exportación de analítica in the same sentence. Raw exports stay open so a workspace can always take its data out. See Without an active subscription.

Common query parameters

Most analytics endpoints share the same window and filters:

A malformed campaignId or agentId (not a UUID) returns 400 VALIDATION_FAILED with the message Invalid query parameters. Filters are never silently dropped.

Dashboard bundle

GET /api/dashboard returns what the dashboard’s home page needs in one request.

curl -sS "https://api.jelliu.co/api/dashboard?tz=America/Bogota" \
  -H "Authorization: Bearer $JELLIU_API_KEY"

Call analytics

Workspace overview

GET /api/analytics/overview accepts days, direction, campaignId and agentId.

{
  "data": {
    "totalInteractions": 1240,
    "completedInteractions": 982,
    "effectiveCompleted": 731,
    "noEffectiveContact": 251,
    "analysed": 874,
    "successes": 214,
    "successRate": 29.27,
    "avgDurationSeconds": 143,
    "avgSentiment": 0.31,
    "sentimentCallCount": 911,
    "totalAgents": 4,
    "totalCampaigns": 6,
    "activeCampaigns": 2,
    "totalContacts": 5120,
    "convertedContacts": 388,
    "dncContacts": 41,
    "channelBreakdown": [
      {
        "channel": "voice",
        "category": "sales",
        "interactions": 1240,
        "completed": 982,
        "effectiveCompleted": 731,
        "analysed": 874,
        "successes": 214,
        "successRate": 29.27,
        "successRateLabel": "conversionRate",
        "avgDurationSeconds": 143,
        "excludedMetrics": []
      }
    ],
    "outcomeBreakdown": { "sale_closed": 214, "rejected": 151, "callback_scheduled": 96, "no_effective_contact": 379 }
  }
}

• Rates such as successRate are percentages from 0 to 100, rounded to two decimals.
• A “success” depends on the campaign category (a sale for sales, a booking for scheduling, and so on). successRateLabel names it.
• successRate is successes over effectiveCompleted, not over completedInteractions. effectiveCompleted is the connected calls that lasted long enough and carried enough turns to have gone either way; noEffectiveContact is the rest of the connected calls. See Counting and coverage.
• analysed of totalInteractions is the coverage: how many of the window’s calls an evaluation actually ran on. A rate whose analysed is far below total describes the analysed slice, not the window.
• outcomeBreakdown carries a no_effective_contact key holding every call that carries an outcome and failed the threshold. It is not a stored outcome and never appears on a call record — the buckets are disjoint, so the slices still sum to the window’s calls with an outcome.
• avgDurationSeconds is null when no voice channel is involved, and excludedMetrics lists metrics that do not apply to a channel or category.
• channelBreakdown rows carry effectiveCompleted and analysed but not noEffectiveContact; derive it as completed - effectiveCompleted for a channel if you need it.

Overview by direction

GET /api/analytics/overview/by-direction?days=90 splits call metrics into inbound, outbound and total. Each has totalCalls, avgDuration (null without voice calls), successes, effectiveCompleted, noEffectiveContact, analysed, successRate, avgSentiment and sentimentCallCount. successRate is successes over effectiveCompleted. It accepts days, campaignId and agentId, which scope all three blocks. A malformed query (a campaignId or agentId that is not a UUID, an unknown direction, a timezone over 50 characters) returns 400 VALIDATION_FAILED with the message Invalid query parameters.

Time series

All three accept days, direction, timezone, campaignId and agentId. Days with no calls are omitted, not returned as zero rows; fill the gaps on your side if your chart needs a continuous axis.

Since 2026-09-16, successes and rejected in these series exclude calls with no effective contact, and the hour heatmap’s successRate divides by effectiveCompleted. An hour whose calls were all two-second pick-ups is not a bad hour to call — it is an hour with no data, and the heatmap’s job is to tell those apart. noEffectiveContact carries the count that used to be folded into rejected, and analysed beside total says how much of the day or hour an evaluation ran on.

curl -sS -G "https://api.jelliu.co/api/analytics/calls-per-day" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  --data-urlencode "days=14" \
  --data-urlencode "timezone=America/Mexico_City" \
  --data-urlencode "agentId=7c1d9f30-5e2a-4a7e-9c8f-91a0b1c2d3e4"

{
  "data": [
    {
      "date": "2026-09-13",
      "total": 88,
      "completed": 71,
      "effectiveCompleted": 54,
      "successes": 17,
      "rejected": 14,
      "noEffectiveContact": 17,
      "analysed": 63,
      "avgSentiment": 0.28,
      "avgFrustration": 0.19,
      "avgDurationSeconds": 131,
      "avgLatencyMs": 1180,
      "costUsd": 13.6412,
      "interruptions": 64
    },
    {
      "date": "2026-09-14",
      "total": 12,
      "completed": 9,
      "effectiveCompleted": 0,
      "successes": 0,
      "rejected": 0,
      "noEffectiveContact": 9,
      "analysed": 0,
      "avgSentiment": null,
      "avgFrustration": null,
      "avgDurationSeconds": 97,
      "avgLatencyMs": null,
      "costUsd": null,
      "interruptions": null
    }
  ]
}

Conversation quality

GET /api/analytics/quality describes how calls went rather than how they ended. It accepts days, direction, campaignId and agentId. Every block carries its own sampleSize, because older calls do not have every measurement.

Agent ranking

GET /api/analytics/agent-ranking returns up to 50 agents, ordered by successes and then by call volume. It accepts days, direction, campaignId and agentId.

Campaign analytics

In both, successRate divides by effectiveCompleted and the league table is sorted by the figure it prints. Before 2026-09-16 a campaign whose calls were mostly two-second pick-ups sank to the bottom of the ranking for calls nobody could have converted, and carried a rejection rate nobody had voiced.

A campaign analytics response may include _degraded, a list of sections that could not be computed (aggregates, outcomeBreakdown). The rest of the response is still valid. An unknown campaign returns 404 CAMPAIGN_NOT_FOUND.

Evaluation criteria and extracted data

Agents can be configured with success criteria and data-collection fields. These two endpoints roll up the results across both voice calls and text conversations:

Both accept days (1 to 365, default 30) and agentId. Here an invalid agentId returns 400 with the message Invalid agentId: expected a UUID. Like the rest of /api/analytics, they need the owner, admin, member or viewer role and an active subscription, and they share the 30 requests per minute analytics budget. A verdict that is not success or failure is counted as unknown, so totals always add up.

Text conversation analytics

Call analytics read calls only. These endpoints cover WhatsApp, web chat, email, Instagram and Messenger threads:

• channel is one of whatsapp, webchat, email, instagram, messenger.
• field must be a simple identifier (a letter, then letters, digits or underscores, up to 64 characters).
• pending threads are still being analyzed and clear by themselves. notAnalysable threads will never be analyzed, so they are a permanent gap in the denominator.
• In the conversation criteria endpoint, successRate is a ratio from 0 to 1 over decided verdicts only (unknown is excluded), or null if nothing was decided. This differs from the 0 to 100 percentages used by call analytics.
• In the field breakdown, a thread where the agent extracted the field but found no value is reported with the literal value (sin dato).

Invalid parameters here return 400 VALIDATION_FAILED with the message Request validation failed and an issue list in details.

Page bundle

GET /api/analytics/page-load computes the whole analytics page in one request. It accepts days, limit, direction, timezone, campaignId and agentId, and returns:

Each section is computed independently. If one fails, it comes back as null (objects) or [] (lists) and the rest of the bundle is unaffected, so check for null before reading nested fields. The campaign filter is not applied to the conversations sections, because text threads do not belong to campaigns.

Campaign KPIs

Each campaign category has business KPIs derived from the data the agent collects (for example revenue_total and avg_ticket for sales, appointments_booked for scheduling, nps_average for surveys).

unit is one of currency, count, percentage, score or seconds. category is one of sales, support, scheduling, surveys, collections, retention, notifications, interview, language_assessment, personal, general.

Support KPIs split escalations from unresolved calls

On 2026-09-15 the support category went from five KPIs to six.

escalated_count used to count rejected as well as escalated_to_human, and its label said so (No resueltos / escalados). That was a workaround: nothing wrote escalated_to_human except the admin warm transfer, which almost nobody uses, so without rejected the card would have sat at a permanent zero. Now that the agent’s own hand-overs are recorded the outcome has real producers, so the two numbers are separated and each is named for what it is.

KPI days are your workspace’s days

Since 2026-09-15 a KPI row is filed under the calendar day in your workspace’s timezone, and KPIs whose key ends in _today (revenue_today) cover the current local day. Before that it was the UTC day, which for a workspace at UTC-5 flipped at 19:00 local — an evening’s sales left “today” and reappeared the next morning. A workspace with no timezone set, or one whose stored value is not a valid IANA id, falls back to America/Bogota.

This does not change the explicit timezone / tz query parameters described under Common query parameters: those still default to UTC and still mean exactly what you pass.

The same workspace clock decides the day everywhere you cannot name a zone yourself — a bare date_from / date_to in a report body, the cost_per_call daily series, and the date column of an analytics export. Internally that is a date_trunc('day', … AT TIME ZONE …) on your workspace’s IANA zone, not on UTC. Counting and coverage has the full table of which surface reads which clock.

curl -sS -G "https://api.jelliu.co/api/analytics/kpi/0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90/timeseries" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  --data-urlencode "kpi=revenue_total" \
  --data-urlencode "days=30"

Custom events

You can record your own product events against the workspace and query them back.

Each event row has id, tenant_id, user_id, event_name, properties, source, timestamp and created_at.

Reports

Reports compute a finished analysis over an explicit date range and return it inline.

GET /api/reports/types lists the available types:

Generate a report

POST /api/reports

curl -sS -X POST "https://api.jelliu.co/api/reports" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "campaign_comparison",
    "period": "monthly",
    "date_from": "2026-08-01T00:00:00Z",
    "date_to": "2026-08-31T23:59:59Z"
  }'

{
  "data": {
    "type": "campaign_comparison",
    "period": { "from": "2026-08-01T00:00:00Z", "to": "2026-08-31T23:59:59Z" },
    "campaigns": [
      {
        "campaignId": "0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90",
        "campaignName": "Renovaciones agosto",
        "totalCalls": 812,
        "connectionRate": 24.1,
        "successRate": 24.1,
        "avgDurationSeconds": 151,
        "avgSentiment": 0.34,
        "totalCost": 285.62,
        "rank": 1
      }
    ]
  }
}

Report shapes

avgDurationSeconds and avgSentiment are null when no call in the group carries that measurement — not 0. outcomeBreakdown in agent_performance holds the stored outcomes and, unlike the analytics endpoints, contains no no_effective_contact key.

Report fields were renamed

successfulCalls was status = 'completed': the call connected. successRate was connected calls over dialled calls: the share of dials that were answered. Neither ever measured success. A report headed “Tasa de éxito: 82%” that means “82% of our dials connected” is the kind of wrong a customer repeats to their own board.

The old names are still sent, with the same values, so a client reading successRate today keeps working and reads exactly what it read yesterday.

campaign_comparison and agent_performance are sorted by connectionRate, which is the same ordering successRate produced, since the two carry the same value.

Exports

Exports produce a file of raw rows asynchronously. You create a job, poll it until it completes, then download the file.

Export types and filters

A filter the type cannot apply is rejected, never ignored:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Export type \"conversations\" cannot filter by campaign_id. Supported filters for \"conversations\": date_from, date_to, agent_id, status."
  }
}

Create an export

POST /api/exports

curl -sS -X POST "https://api.jelliu.co/api/exports" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "calls",
    "format": "csv",
    "filters": {
      "date_from": "2026-09-01T00:00:00Z",
      "date_to": "2026-09-14T23:59:59Z",
      "outcome": "sale_closed"
    }
  }'

{
  "data": {
    "id": "3e1f0a9c-7b2d-4c6e-8f10-2a3b4c5d6e7f",
    "tenant_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "user_id": "user_2abcDEF123",
    "type": "calls",
    "format": "csv",
    "status": "pending",
    "filters": { "date_from": "2026-09-01T00:00:00Z", "date_to": "2026-09-14T23:59:59Z", "outcome": "sale_closed" },
    "row_count": null,
    "file_size_bytes": null,
    "file_url": null,
    "error": null,
    "started_at": null,
    "completed_at": null,
    "expires_at": null,
    "created_at": "2026-09-14T16:02:11.412Z"
  }
}

curl -sS -L "https://api.jelliu.co/api/exports/3e1f0a9c-7b2d-4c6e-8f10-2a3b4c5d6e7f/download" \
  -H "Authorization: Bearer $JELLIU_API_KEY" \
  -o calls.csv

Export limits

A job that is not completed yet returns 404 with Export file is not ready for download. An expired file returns 410 with Export file has expired, or 404 with Export file has expired or is no longer available. Create a new export in either case.

Errors

See Errors for the envelope.

Limits and caching

• Rate limits. Every endpoint under /api/analytics, /api/analytics/analysis/* included, shares a budget of 30 requests per minute per workspace, on top of the general limit. Use /api/analytics/page-load or /api/dashboard instead of many individual calls. See Rate limits.
• Freshness. Aggregates are cached on the server for up to a few minutes and responses carry Cache-Control: private, max-age=30, stale-while-revalidate=900. A call that just ended may take a short while to show up. Do not poll analytics faster than once a minute.
• Conditional requests. overview, agent-ranking, quality, top-campaigns and /api/dashboard return a weak ETag. Send it back in If-None-Match to receive 304 Not Modified when nothing changed.
• Windows. days is capped at 365 for analytics and at 90 for custom events. Reports cover at most one year.

Related