Usage

GET /v1/usage returns everything your account is entitled to and how much of it you have consumed in the current billing cycle — plan, cycle dates, and a meter per resource. Use it to show a usage widget, to decide whether to submit an FFmpeg job, or to check how many profile slots are left before you mint a connect link.

Publishing is unlimited on every paid plan (see Posts), so uploads.limit is null — the used counter still runs as a meter, not a cap.

Request

curl https://api.madiad.com/v1/usage \
  -H "Authorization: Bearer $MADIAD_API_KEY"

The endpoint is scoped entirely to the key’s own account — it takes no parameters and can never return another account’s figures. It is a GET: it consumes no FFmpeg minutes and no uploads, only the per-minute rate limit.

Response

{
  "plan": { "id": "growth", "name": "Growth", "price_vnd_monthly": 390000 },
  "status": "active",
  "period": { "start": "2026-07-07", "renews_on": "2026-08-07", "expires_on": null },
  "uploads": { "used": 180, "limit": null, "remaining": null },
  "ffmpeg_minutes": { "used": 12, "limit": 150, "remaining": 138 },
  "profiles": { "used": 4, "limit": 4, "remaining": 0 },
  "direct_messages": {
    "used": 0,
    "limit": 0,
    "remaining": 0,
    "day": "2026-07-20",
    "included": false
  },
  "api_keys": { "used": 2, "limit": null, "remaining": null },
  "features": { "schedule": true, "queue": true, "analytics": true, "webhooks": true }
}

Meters

Every metered resource uses the same three fields:

Field	Meaning
`used`	Consumed so far in the current cycle (for `direct_messages`, so far today).
`limit`	The allowance. `null` means unlimited. `0` means the resource is not included in your plan.
`remaining`	`limit - used`, floored at 0. `null` when `limit` is `null`.

Treat limit: null as unlimited, not zero — a remaining ?? 0 fallback will wrongly show your users as out of allowance.

Fields

Field	Meaning
`plan`	The active plan’s id, display name, and monthly price in VND (`null` for Custom).
`status`	Account status. Always `active` in this response: an `expired` or `banned` account is rejected with `403` before this endpoint runs (see the errors below).
`period.start`	First day of the current cycle, `YYYY-MM-DD`.
`period.renews_on`	The day the cycle rolls over and the meters reset.
`period.expires_on`	When the paid term ends, if one is set — otherwise `null`.
`uploads`	Posts published this cycle. `limit` is `null` on every paid plan.
`ffmpeg_minutes`	FFmpeg minutes this cycle. The allowance is account-wide — all your brands draw from this one pool.
`profiles`	Connected profiles against your plan’s cap.
`direct_messages`	Today’s DM count. `included: false` means engagement is not part of your plan.
`api_keys`	Active (non-revoked) keys.
`features`	Feature flags for the active plan.

Cycle dates

Your cycle is anchored to the day your plan was activated, evaluated in Vietnam time (UTC+7) — not the first of the calendar month. A plan activated on the 7th resets on the 7th. An anchor day that does not exist in a shorter month is clamped to that month’s last day. period.start and period.renews_on always report the real dates, so read them rather than computing month boundaries yourself.

Checking before you act

# Only submit an FFmpeg job if minutes remain (null = unlimited).
REMAINING=$(curl -s https://api.madiad.com/v1/usage \
  -H "Authorization: Bearer $MADIAD_API_KEY" | jq '.ffmpeg_minutes.remaining')

if [ "$REMAINING" = "null" ] || [ "$REMAINING" -gt 0 ]; then
  echo "OK to submit"
fi

Errors

Status	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key.
`403`	`forbidden`	The account is `expired` or `banned`. An expired account starts publishing again the moment a renewal is credited.
`429`	`rate_limited`	Per-minute request rate limit exceeded.

See Errors for the full reference.

Get Started

Concepts

Integrations

Request

Response

Meters

Fields

Cycle dates

Checking before you act

Errors

​Request

​Response

​Meters

​Fields

​Cycle dates

​Checking before you act

​Errors

Request

Response

Meters

Fields

Cycle dates

Checking before you act

Errors