Skip to content
Talki DevelopersBeta

usage.threshold_reached

POST

A call ends leaving 25% or less of the period’s allowance: the plan’s included minutes plus any extra minutes. Sent once per crossing, and not on a plan with no minute cap. When the same call also sends usage.extra_credits_low, this event is not sent for that crossing. Sent to the account’s webhooks and to the app of the partner that pays for the account; no other app receives it.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
X-Talki-Signature
required
string

t=<unix seconds>,v1=<hex HMAC-SHA256>, the HMAC computed over <t>.<raw body> with the signing secret. During a secret rotation it carries one v1 per secret: accept the request if any matches.

X-Talki-Event
required
string

The event type, as in type.

X-Talki-Delivery
required
string

The event ID, as in id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
id
required
Id

The event’s ID, evt_ and 32 hex characters. Equal to the X-Talki-Delivery header and unchanged on a redelivery: deduplicate on it.

string
type
required
string
Allowed values: usage.threshold_reached
created_at
required
Created At

When the event was written, ISO 8601 with a +00:00 offset, possibly with microseconds. Parse it as an instant.

string format: date-time
api_version
required
Api Version

The dated contract version data is shaped for: the endpoint’s version on a webhook, the app’s on an app event.

string
account_id
required
Account Id

The Talki account the event happened on.

string
livemode
required
Livemode

false for an event from a sandbox account.

boolean
origin
required
Any of:
EventOrigin
object
source
required
Source

Where the change came from: voice (the assistant, during a call), dashboard (a person in the Talki web or mobile app), api (a credential through the API) or system (a rule Talki applied on its own). New values may be added; treat one you do not recognise as unknown.

string
credential_id
required
Any of:
string
idempotency_key
required
Any of:
string
installation_id
Any of:
string
data
required

The event’s payload.

object
used_seconds
required
Used Seconds

Seconds used in the current billing period, this call included: plan and extra minutes together.

integer
included_seconds
required
Included Seconds

Seconds included in the period, without extra minutes: the same figure as Usage.included_seconds.

integer
allowance_seconds
required
Allowance Seconds

Everything the account may spend in the period: included_seconds plus the extra seconds it held when the period began and any added since. Equal to included_seconds when it has none.

integer
remaining_seconds
required
Remaining Seconds

allowance_seconds minus used_seconds, never below 0.

integer
percent_used
required
Percent Used

used_seconds as a percentage of allowance_seconds, to one decimal place. Above 100 when a call ran past the allowance.

number
extra_seconds
required
Extra Seconds

Extra seconds still unspent after this call; 0 when the account has none.

integer
minutes_used
required
Minutes Used

used_seconds rounded to the nearest whole minute. For display.

integer
minutes_included
required
Minutes Included

Minutes included in the period, without extra minutes: Usage.included_seconds in minutes.

integer
minutes_remaining
required
Minutes Remaining

remaining_seconds in whole minutes, rounded down. For display.

integer
seconds_used
required
Seconds Used

The same value as used_seconds.

integer
seconds_included
required
Seconds Included

The same value as included_seconds.

integer
seconds_allowance
required
Seconds Allowance

The same value as allowance_seconds.

integer
seconds_remaining
required
Seconds Remaining

The same value as remaining_seconds.

integer
extra_seconds_balance
required
Extra Seconds Balance

The same value as extra_seconds.

integer
Example
{
  "id": "evt_04d8e87897db4ecab459a456ea55e754",
  "type": "usage.threshold_reached",
  "created_at": "2026-09-22T15:04:06.218734+00:00",
  "api_version": "2026-10-01",
  "account_id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
  "livemode": true,
  "origin": {
    "source": "voice",
    "credential_id": null,
    "idempotency_key": null
  },
  "data": {
    "minutes_used": 271,
    "minutes_included": 300,
    "minutes_remaining": 89,
    "seconds_used": 16245,
    "seconds_included": 18000,
    "seconds_remaining": 5355,
    "extra_seconds_balance": 3600,
    "seconds_allowance": 21600,
    "percent_used": 75.2,
    "used_seconds": 16245,
    "included_seconds": 18000,
    "allowance_seconds": 21600,
    "remaining_seconds": 5355,
    "extra_seconds": 3600
  }
}

Responses

Section titled “ Responses ”

2XX

Section titled “2XX”

Any 2xx acknowledges the event. Any other status, a redirect, or no answer within 10 seconds is a failure and is retried; 410 disables a webhook endpoint at once.