Jelliu API documentation

curl -G https://api.jelliu.co/api/analytics/top-campaigns \
     -H "Authorization: Bearer <token>" \
     -d agentId=2f2d8b4d-aa6f-41e0-9d3e-4d61e1b07a11 \
     -d days=30 \
     -d direction=outbound \
     -d limit=5

{
  "data": [
    {
      "campaignId": "3f2b8c1e-7a4d-4e9b-9c21-5d8e6f1a2b30",
      "campaignName": "Reactivación clientes septiembre",
      "agentName": "Valentina — Ventas",
      "status": "active",
      "channel": "voice",
      "category": "sales",
      "totalInteractions": 268,
      "completed": 231,
      "successes": 71,
      "rejected": 52,
      "successRate": 30.74,
      "rejectionRate": 19.4,
      "successRateLabel": "conversionRate",
      "avgDurationSeconds": 201,
      "avgSentiment": 0.3,
      "avgFrustration": 0.21,
      "avgLatencyMs": 1210,
      "costUsd": 33.1204,
      "costPerCallUsd": 0.1743
    },
    {
      "campaignId": "b71e0d42-19c5-4a8f-a3e6-0c94d2f7e815",
      "campaignName": "Recordatorio de citas Clínica Norte",
      "agentName": "Andrés — Soporte",
      "status": "active",
      "channel": "voice",
      "category": "scheduling",
      "totalInteractions": 96,
      "completed": 88,
      "successes": 22,
      "rejected": 5,
      "successRate": 25,
      "rejectionRate": 5.21,
      "successRateLabel": "bookingRate",
      "avgDurationSeconds": 142,
      "avgSentiment": 0.44,
      "avgFrustration": 0.09,
      "avgLatencyMs": 1080,
      "costUsd": 9.8712,
      "costPerCallUsd": 0.1175
    }
  ]
}

Filters. days sets the window (rolling, ending now; missing or out-of-range values become 30). direction and agentId narrow the calls counted (agentId matches the agent that served each call). campaignId and timezone are not accepted and are ignored, even when malformed. limit caps the rows.

What counts as a success. A completed call whose outcome is a success outcome of any category, as in GET /api/analytics/overview. rejected counts explicit refusals only (rejected, appointment_canceled, payment_refused, churned, candidate_unqualified), not voicemails or no-answers.

Ordering. successRate descending; campaigns with no completed call sort last. Ties have no guaranteed order.

No data. An empty array when no campaign had calls. Within a row, averages are null when nothing carried the measurement, except avgDurationSeconds, which is 0 for a voice campaign without completed calls and null for other channels.

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; each API instance also keeps a 60-second local copy. 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 campaigns ranked by success rate (successes over completed calls, highest first), each with volume, rejections, duration, sentiment, frustration, latency and cost. Only campaigns with at least one call in the window appear; deleted campaigns never do. The system "Manual Conversations" bucket can appear when it has calls. **Filters.** `days` sets the window (rolling, ending now; missing or out-of-range values become 30). `direction` and `agentId` narrow the calls counted (`agentId` matches the agent that served each call). `campaignId` and `timezone` are not accepted and are ignored, even when malformed. `limit` caps the rows. **What counts as a success.** A completed call whose outcome is a success outcome of any category, as in `GET /api/analytics/overview`. `rejected` counts explicit refusals only (`rejected`, `appointment_canceled`, `payment_refused`, `churned`, `candidate_unqualified`), not voicemails or no-answers. **Ordering.** `successRate` descending; campaigns with no completed call sort last. Ties have no guaranteed order. **No data.** An empty array when no campaign had calls. Within a row, averages are `null` when nothing carried the measurement, except `avgDurationSeconds`, which is `0` for a voice campaign without completed calls and `null` for other channels. **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; each API instance also keeps a 60-second local copy. 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:

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.

limitintegerOptional1-100Defaults to 10

Maximum number of campaigns to return. Missing, non-integer or out-of-range values silently become 10; they are never rejected.

Response headers

ETagstringOptional

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

Response

Campaigns ranked by success rate.

datalist of objectsOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

Ordering. successRate descending; campaigns with no completed call sort last. Ties have no guaranteed order.

Idempotency. Safe to retry: this is a read.

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.