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. Two 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.

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.

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,
    "successes": 214,
    "successRate": 21.79,
    "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,
        "successes": 214,
        "successRate": 21.79,
        "successRateLabel": "conversionRate",
        "avgDurationSeconds": 143,
        "excludedMetrics": []
      }
    ],
    "outcomeBreakdown": { "sale_closed": 214, "rejected": 402, "callback_scheduled": 96 }
  }
}

• 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.
• avgDurationSeconds is null when no voice channel is involved, and excludedMetrics lists metrics that do not apply to a channel or category.

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), successRate, avgSentiment and sentimentCallCount.

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.

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,
      "successes": 17,
      "rejected": 22,
      "avgSentiment": 0.28,
      "avgFrustration": 0.19,
      "avgDurationSeconds": 131,
      "avgLatencyMs": 1180,
      "costUsd": 13.6412,
      "interruptions": 64
    },
    {
      "date": "2026-09-14",
      "total": 12,
      "completed": 9,
      "successes": 0,
      "rejected": 3,
      "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

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. 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.

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,
        "successRate": 24.1,
        "avgDurationSeconds": 151,
        "avgSentiment": 0.34,
        "totalCost": 285.62,
        "rank": 1
      }
    ]
  }
}

Report shapes

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. Analytics endpoints are limited to 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