Jelliu API documentation

curl -G https://api.jelliu.co/api/analytics/agent-ranking \
     -H "Authorization: Bearer <token>" \
     -d agentId=2f2d8b4d-aa6f-41e0-9d3e-4d61e1b07a11 \
     -d campaignId=0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90 \
     -d days=30 \
     -d direction=outbound

{
  "data": [
    {
      "agentId": "8d4a6e2f-3b1c-4f7a-9e05-2c6b8d1f4a93",
      "agentName": "Valentina — Ventas",
      "totalCalls": 268,
      "completed": 231,
      "successes": 71,
      "rejected": 52,
      "conversionRate": 30.74,
      "rejectionRate": 19.4,
      "avgSentiment": 0.3,
      "sentimentCallCount": 180,
      "avgFrustration": 0.21,
      "avgDurationSeconds": 201,
      "avgLatencyMs": 1210,
      "latencyCallCount": 190,
      "interruptionRate": 8.6,
      "agentTalkShare": 63.2,
      "costUsd": 33.1204,
      "costPerCallUsd": 0.1743,
      "avgSuccessScore": 68.9
    },
    {
      "agentId": "c25f9a70-6e8b-4d13-b4a2-7f1e3c9d5b68",
      "agentName": "Andrés — Soporte",
      "totalCalls": 144,
      "completed": 125,
      "successes": 26,
      "rejected": 12,
      "conversionRate": 20.8,
      "rejectionRate": 8.33,
      "avgSentiment": 0.41,
      "sentimentCallCount": 118,
      "avgFrustration": 0.13,
      "avgDurationSeconds": 163,
      "avgLatencyMs": 1110,
      "latencyCallCount": 97,
      "interruptionRate": 6.9,
      "agentTalkShare": 57.4,
      "costUsd": 15.1406,
      "costPerCallUsd": 0.1561,
      "avgSuccessScore": 76.2
    }
  ]
}

Calls are attributed to the agent that served them, so manual calls without a campaign count, and a campaign reassigned to another agent does not move its history. Older calls that predate that attribution fall back to the campaign’s agent. Only agents with at least one call in the window appear; deleted agents never do.

Filters. days sets the window (rolling, ending now; missing or out-of-range values become 30). direction, campaignId and agentId narrow the calls counted; with agentId you get a single row (or none), which is the per-agent scorecard. timezone is accepted but not used (a value longer than 50 characters is still a 400).

Ordering. successes descending, then totalCalls descending; at most 50 rows.

No data. An empty array when no agent had calls. Within a row, counts and rates are 0, while averages, interruptionRate, agentTalkShare and the cost fields are null when no call carried the measurement (see sentimentCallCount and latencyCallCount).

Idempotency. Safe to retry: this is a read.

Consistency. Cached for 5 minutes, then served stale for up to 30 minutes while a background refresh runs. The response carries a weak ETag for If-None-Match.

Access

Required scope: read. Signed-in users need the owner, admin, member or viewer role.
Rate limit: Analytics — 30 requests/min per workspace, in addition to the general API budget of your plan. See Rate limits.
Plan: Available on every plan. A workspace without an active subscription (active, trialing or past due) gets 403 BILLING_ERROR.

Returns a leaderboard of agents with, for each, conversion, rejections, sentiment, frustration, duration, response latency, interruption rate, talk share, cost and the voice provider's success score. It compares agents on how they converse, not only on whether they closed. Calls are attributed to the agent that served them, so manual calls without a campaign count, and a campaign reassigned to another agent does not move its history. Older calls that predate that attribution fall back to the campaign's agent. Only agents with at least one call in the window appear; deleted agents never do. **Filters.** `days` sets the window (rolling, ending now; missing or out-of-range values become 30). `direction`, `campaignId` and `agentId` narrow the calls counted; with `agentId` you get a single row (or none), which is the per-agent scorecard. `timezone` is accepted but not used (a value longer than 50 characters is still a `400`). **Ordering.** `successes` descending, then `totalCalls` descending; at most 50 rows. **No data.** An empty array when no agent had calls. Within a row, counts and rates are `0`, while averages, `interruptionRate`, `agentTalkShare` and the cost fields are `null` when no call carried the measurement (see `sentimentCallCount` and `latencyCallCount`). **Idempotency.** Safe to retry: this is a read. **Consistency.** Cached for 5 minutes, then served stale for up to 30 minutes while a background refresh runs. The response carries a weak `ETag` for `If-None-Match`. **Access** - **Required scope:** `read`. Signed-in users need the owner, admin, member or viewer role. - **Rate limit:** Analytics — 30 requests/min per workspace, in addition to the general API budget of your plan. See [Rate limits](/rate-limits). - **Plan:** Available on every plan. A workspace without an active subscription (active, trialing or past due) gets `403 BILLING_ERROR`.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

Query parameters

daysintegerOptional1-365Defaults to 30

Size of the reporting window in days, ending now. On most analytics routes a missing or out-of-range value falls back to 30 instead of being rejected; the operation says when it is strict.

directionenumOptionalDefaults to all

Which calls to count: inbound (calls the agent answered), outbound (calls the agent placed) or all (both).

Allowed values:

campaignIdstringOptionalformat: "uuid"

Scope every number to one campaign of the workspace. Omit it to aggregate across all campaigns and manual calls.

agentIdstringOptionalformat: "uuid"

Scope every number to one agent — the agent that served each call, so manual (campaign-less) calls count. Omit it to aggregate across agents.

Response headers

ETagstringOptional

Weak entity tag of the body. Send it in If-None-Match on the next request.

Response

Agents ranked by successes.

datalist of objectsOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

Ordering. successes descending, then totalCalls descending; at most 50 rows.

Idempotency. Safe to retry: this is a read.

Consistency. Cached for 5 minutes, then served stale for up to 30 minutes while a background refresh runs. The response carries a weak ETag for If-None-Match.

Access

Required scope: read. Signed-in users need the owner, admin, member or viewer role.
Rate limit: Analytics — 30 requests/min per workspace, in addition to the general API budget of your plan. See Rate limits.
Plan: Available on every plan. A workspace without an active subscription (active, trialing or past due) gets 403 BILLING_ERROR.