List call metrics by hour of day

curl -G https://api.jelliu.co/api/analytics/calls-by-hour \
     -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-urlencode timezone=America/Bogota

{
  "data": [
    {
      "hour": 9,
      "total": 38,
      "completed": 33,
      "effectiveCompleted": 24,
      "successes": 10,
      "noEffectiveContact": 9,
      "analysed": 31,
      "completionRate": 86.84,
      "successRate": 41.67,
      "avgSentiment": 0.36
    },
    {
      "hour": 10,
      "total": 52,
      "completed": 47,
      "effectiveCompleted": 34,
      "successes": 15,
      "noEffectiveContact": 13,
      "analysed": 44,
      "completionRate": 90.38,
      "successRate": 44.12,
      "avgSentiment": 0.33
    },
    {
      "hour": 15,
      "total": 41,
      "completed": 34,
      "effectiveCompleted": 0,
      "successes": 0,
      "noEffectiveContact": 34,
      "analysed": 0,
      "completionRate": 82.93,
      "successRate": 0,
      "avgSentiment": null
    }
  ]
}

Returns one row per hour of the day (0-23) that had at least one call in the window, with volume, completion rate, success rate and average sentiment. Use it to find the hours when people pick up and convert, for example to tune a campaign’s calling schedule.

Filters. days sets the window (rolling, ending now; missing or out-of-range values become 30). direction, campaignId and agentId narrow every row. timezone decides the hour a call falls in (pass the zone your contacts live in); an unknown zone name silently falls back to UTC.

Ordering. Ascending by hour, at most 24 rows.

No data. Hours without calls are omitted. completionRate and successRate are 0 when their denominator is zero; avgSentiment is null when no call in that hour was scored.

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.

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. Requires an active subscription (active, trialing or past_due); without one the request is refused with 403 BILLING_ERROR (metadata.kind: subscription_required).

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.

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.

timezonestringOptional<=50 characters

IANA time zone the day and hour buckets are computed in (default UTC). An unknown zone falls back to UTC; a value longer than 50 characters is rejected with 400.

Response

Hourly rows in ascending hour order.

datalist of objectsOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error