Channel usage and corrections

The APIs on this page get channels' daily participant time and later corrections to historical usage, for checking usage.

How it's counted:

• Milliseconds are accumulated over the time each member is actually connected to media, split into days by the statistics time zone, then summed per app, date and media category (audio, video) and rounded up to minutes.
• Both publishers and subscribers count; time holding a seat without being connected to media doesn't.
• Categorized by the channel's media: turning off the camera in a video channel still counts as video.

These minutes aren't what you're charged

Once new billing is enabled, charges use standard audio/video duration: converted by the resolution tier of video received, with calls and channels sharing the app's balance, rounded on the app's monthly total. audio_minutes, video_minutes and billable_minutes on this page can't be used directly as charged standard minutes. From the day of switching to new billing, these daily statistics and corrections no longer produce duplicate plan media fees.

Get daily usage

GET/{org_name}/{app_name}/rtc/channel-stats

Path parameters

For org_name and app_name, see Server overview. Uses the App Token.

Query parameters

Parameter	Type	Required	Description
from	String	Yes	Start date, YYYY-MM-DD
to	String	Yes	End date, inclusive. Not before from, at most 92 days in total

Future dates, and dates before the last 180 statistics days, can't be queried.

Example request

Replace the dates with a valid range:

curl "$IM_API/$ORG/$APP/rtc/channel-stats?from=2026-10-01&to=2026-10-09" -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK:

Field	Description
timezone	Statistics time zone
finalized_through	The date finalized through; numbers on and before it won't change. null if none yet
items	One entry per day, see below

Daily field	Type	Description
date	String	Date
status	String	finalized, provisional (may still change), pending (not yet aggregated)
finalized	Boolean	Whether it's finalized
audio_participant_ms, video_participant_ms	String / null	Total participant milliseconds as a decimal string. In JavaScript, don't convert directly to a number: it may exceed the safe integer range
audio_estimated_ms, video_estimated_ms	String / null	The estimated part of the total, already included in it; don't add it again
audio_minutes, video_minutes	Integer / null	Minutes after summing the day and rounding
version	Integer / null	Version of the day's statistics

Days not yet finalized and without data return pending and null, which doesn't mean zero usage; only finalized days without data return 0. Late media events delay finalization, so there's no fixed time each day by which a day is finalized.

Errors

Invalid dates or ranges return 400 invalid_argument; for common errors such as authentication, see Error codes.

Get usage corrections

If, after a day is finalized, media records arrive proving members were connected, the server automatically creates a correction for that day. This API lists those corrections; it's read-only, with no APIs to write or manually confirm them.

GET/{org_name}/{app_name}/rtc/channel-usage-adjustments

Path parameters

As in Get daily usage.

Query parameters

limit and cursor, see Pagination.

Example request

curl "$IM_API/$ORG/$APP/rtc/channel-usage-adjustments?limit=20" -H "Authorization: Bearer $APP_TOKEN"

Response

Returns 200 OK with items and next_cursor. Each item:

Field	Type	Description
date, media	String	Which day is corrected, and audio or video
status	String	pending awaiting the billing system; confirmed accepted by the billing system, which doesn't mean invoiced or settled
proposal_version	Integer	Version of the current correction
target_version	Integer	Version accepted by the billing system
participant_ms, minutes	String, Integer	Usage already accepted
proposed_participant_ms, proposed_minutes	String, Integer	The day's total usage after correction. This is the corrected total, not an increment to be charged in full again
billing_adjustment_id	String / null	ID under which the billing system recorded this correction, null if not yet recorded

Errors

Invalid cursor returns 400 invalid_argument; for others see Error codes.

Billing rules

Channel usage corresponds to the meter items rtc_channel_audio_minutes and rtc_channel_video_minutes. Whether they're charged, how much is included and the unit price all follow the plan; existing plans without these meter items aren't automatically charged at call prices.

How corrections are billed: the difference is calculated with the original period's plan, included amounts and rounding.

Original period's invoice	The difference goes to
Still a draft	Included when the draft is generated or recalculated. Existing drafts must be recalculated to include newly recorded differences
Invoiced or settled	The original invoice stays as is; the difference carries over to the next or a later available draft

• Credits reduce the amount due to 0 at most, and the rest carries over; amounts beyond each invoice's adjustment cap are kept for later too.
• Automatic adjustments can't be deleted through the manual deletion API.
• If a historical period was already compensated manually, check with the platform to avoid compensating twice.

For invoice rules, see Plans and billing.