Usage and plan limits

Your plan sets limits on stored hours, new uploads, watched minutes, domains, projects and playback quality. This page shows how to read your usage and your limits, and what happens when you reach one. This guide is written in simple English.

Before you start

API in TEST: https://test-api.segmnt.cloud
GET /v1/billing/plan uses your session cookie (the dashboard session).
GET /v1/projects/{projectId}/usage accepts a project API key (Authorization: Bearer sk_...) or your session cookie.
Days are UTC dates in the form YYYY-MM-DD.

Both answers carry numbers in seconds or minutes. Stored time is in seconds; watched time is in minutes and is rounded down.

1. Usage of one project

GET /v1/projects/{projectId}/usage returns the stored seconds of the project and the minutes watched in a date range.

Query	Required	Default	Notes
`from`	No	Start of the current month	Inclusive. `YYYY-MM-DD`.
`to`	No	Today	Inclusive. `YYYY-MM-DD`.

curl "$BASE/v1/projects/$PROJECT_ID/usage?from=2026-10-01&to=2026-10-14" \
  -H "Authorization: Bearer $SEGMNT_KEY"

{
  "projectId": "prj_9xR4tL",
  "from": "2026-10-01",
  "to": "2026-10-14",
  "storedSeconds": 5400,
  "watchedMinutes": 842
}

Notes:

storedSeconds is the total length of the project’s videos now, not only in the period. It counts videos that are encoding, ready or held for review, and it uses quality weighting. Deleting a video lowers it on the next call.
watchedMinutes counts only the period you asked for.
A project API key works only for its own project. A key for another project gets 404 not_found, the same as an unknown project.
from after to, or a bad date, gets 400 invalid_request.

Account totals (every project together) are in the next call.

2. Your plan, limits and usage

GET /v1/billing/plan returns your plan, its status, the current period, the limits and your usage for the account.

curl "$BASE/v1/billing/plan" \
  -H "Cookie: segmnt_session=$SEGMNT_SESSION"

{
  "plan": { "id": "free", "name": "Free" },
  "status": "active",
  "currentPeriod": {
    "start": "2026-10-01T00:00:00.000Z",
    "end": "2026-11-01T00:00:00.000Z"
  },
  "limits": {
    "storedSeconds": 7200,
    "watchedMinutesPerPeriod": 2000,
    "verifiedDomains": 1,
    "maxQuality": 720,
    "whiteLabel": false
  },
  "usage": { "storedSeconds": 5400, "watchedMinutes": 842, "verifiedDomains": 1 }
}

Notes:

plan.name is Pilot while a pilot account is inside its 30-day window.
status is one of active, pilot, past_due, canceled.
currentPeriod is the current UTC month. Watched minutes reset at the start of each month. The start is inclusive and the end is exclusive.
In limits, null means no limit.
maxQuality is the highest height you may play (720 = 720p, 1080 = 1080p, 2160 = 4K): Free plays up to 720p, Starter up to 1080p, Pro and Agency up to 4K. whiteLabel tells you if you may hide our logo.
usage is for the whole account: stored seconds now, watched minutes in the current period, and verified domains.
This call needs the session cookie. An API key cannot read it.
The new-upload and project limits are enforced, but they are not in this answer yet. They are in the limits table below.

3. Limits

Limit	Free	Pilot (30 days)	Paid
Stored hours	2 h	10 h	Per plan
New uploads	2 h per month	10 h in total	Per plan
Watched minutes	2,000 per month	20,000	Per plan
Verified domains	1	3	Per plan
Projects	1	3	Per plan
Highest quality	720p	1080p	Per plan
Our logo on the player	Shown	Hidden	Per plan

The monthly counters (new uploads and watched minutes) reset at the start of each UTC month. Stored hours do not reset; they fall when you delete a video. A pilot is different: its new uploads are capped for the whole pilot, not per month.
The pilot runs for 30 days and needs no credit card. When it ends, the account returns to its plan (usually Free).
Paid plan numbers come from the plan catalog. See Plans, checkout and payment for the prices and how to buy a plan.

4. Quality weighting

Hours count by the quality of the source file, for stored time and for uploaded time:

Source quality	1 hour counts as
1080p or lower	1 hour
1440p	2 hours
4K (2160p)	4 hours

Example: a 30-minute 4K lesson counts as 2 hours of stored time. A 30-minute 1440p lesson counts as 1 hour. This keeps the low price honest for everyone: a 4K file costs us more to store and to send.

5. What happens at a limit

When the account is over a limit, the API answers 403 plan_limit_reached on the action that would pass it. It can happen on:

Action	Endpoint
Start a new upload	`POST /v1/projects/{projectId}/uploads`
Get a playback link	`POST /v1/projects/{projectId}/videos/{videoId}/playback-tokens`
Create a project	`POST /v1/projects`
Add a domain	`POST /v1/projects/{projectId}/domains`

What stops depends on the plan:

Free, Starter and Pilot: uploads stop at the limit, and playback stops at the watched-minutes limit. Starter’s wall is watch time.
Pro and Agency: uploads stop at the limit. Playback never stops: past the included minutes, extra watch time is cheap pay-as-you-go and is added to your next invoice. No “call sales” wall and no sudden stop.

For Free, Starter and Pilot playback we stop issuing new playback links. A link that was already issued keeps working until it expires (4 hours by default). This is why playback can overrun the minute limit a little before it stops. GET /v1/billing/plan returns the extra watched minutes in usage.overageMinutes. This number is always 0 for Free, Starter and Pilot: those plans stop playback at the watched-minutes limit, so they are never billed for overage. The pay-as-you-go amount applies only to Pro and Agency, where you can see it here before the next invoice. The invoice itself (A14) is not live yet. You do not lose data. Delete videos or remove domains to go back under a limit, or upgrade to raise it. When the month (or the pilot) ends, the counters reset.

6. Errors

Errors use application/problem+json. Use the code field in your code, not the text. The type field links to https://docs.segmnt.cloud/errors/{code}.

Status	`code`	Meaning	What to do
400	`invalid_request`	`from`/`to` is not a date, or `from` is after `to`	Fix the range. Do not retry.
401	`unauthorized`	Missing, wrong or expired session or key	Sign in again, or check the key.
403	`plan_limit_reached`	Over a plan limit (stored, upload, watched, domain or project)	Delete something, wait for the period to end, or upgrade.
405	`method_not_allowed`	Wrong method for the URL	Use `GET`.
404	`not_found`	Wrong project id, or the key is for another project	Check the ids.

Tested in TEST

Checked against https://test-api.segmnt.cloud on 14 Oct 2026:

GET /v1/billing/plan with no session → 401 unauthorized.
GET /v1/projects/{projectId}/usage with no credential → 401 unauthorized.
POST on both routes → 405 method_not_allowed.

The full path (a project key and a session, the weighted stored total, watched minutes, the plan limits and the 403 plan_limit_reached cases on upload, playback link, project and domain) is proved against TEST by our end-to-end tests. The route behaviour and the limit checks are also covered by our API unit tests.

Start here

Guides

Usage and plan limits

Before you start

1. Usage of one project

2. Your plan, limits and usage

3. Limits

4. Quality weighting

5. What happens at a limit

6. Errors

Tested in TEST

​Before you start

​1. Usage of one project

​2. Your plan, limits and usage

​3. Limits

​4. Quality weighting

​5. What happens at a limit

​6. Errors

​Tested in TEST

Before you start

1. Usage of one project

2. Your plan, limits and usage

3. Limits

4. Quality weighting

5. What happens at a limit

6. Errors

Tested in TEST