Review usage and export CSV

In Usage, select the environment and 24 hours, 7, 30, or 90 days. Readers can query and export. The table includes deleted assets that retain attribution. The period filters delivery and ingest; storage is the latest valid observation, rather than history.

What each family measures

Family	Measurement	Boundary
Storage	Known S3 asset objects, with deduplicated keys	Excludes physical disk space and incomplete multipart uploads
Delivery	Exact bytes of completed HTTP 200/206 bodies	Does not measure watch time, client confirmation, or external cache traffic
Registered ingest	External primary source accepted once	Excludes transport retries and internal copies
Added tracks	External audio/text sources accepted once	Excludes internally copied tracks; text has no audio duration

A canceled or truncated body leaves confirmed bytes unknown; a lost completion can remain pending. Storage scans are not atomic and a failure preserves the latest valid reading with its status. Unmeasured, No history, Stale, and zero are different results. History before registration is not reconstructed.

Query with the SDK

In your backend with video:read permission:

const report = await orilla.usage.retrieve({
  timeframe: ["7:days"],
  page: 1,
  limit: 25,
});
console.log(report.data.storage, report.data.delivery);
console.log(report.data.ingest, report.data.auxiliary_ingest);
const bytes = report.data.storage.observed_bytes;
const exactBytes = bytes === null ? null : BigInt(bytes);

Known bytes and milliseconds are decimal strings to preserve precision. Do not convert large integers to Number. Check coverage counters: a known sum can be partial. ingest and auxiliary_ingest may be absent on older servers; do not replace them with zero.

GET /v1/usage uses Bearer or a session; /video/v1/usage uses Basic. It accepts an asset_id UUID, page starting at 1, and limit up to 100 (default 25). The SDK transforms assetId into asset_id. timeframe accepts a duration or two Unix timestamps in seconds for the [start, end) interval, up to 90 days.

Export the full scope

Export CSV downloads all assets in the environment and period, regardless of the visible page. Changing scope cancels local preparation; a failure allows retrying. The dashboard explicitly requests v3.

import { writeFile } from "node:fs/promises";

const csv = await orilla.usage.exportCSV(
  {
    timeframe: ["7:days"],
    schema: "v3",
  },
  { signal: new AbortController().signal },
);
await writeFile("usage.csv", csv, "utf8");

Schema	Columns	Content
v1, API/SDK default	28	Storage and delivery
v2, explicit	34	Adds primary ingest
v3, explicit	42	Adds auxiliary tracks

The first row is summary; asset rows follow in UUID order. The file preserves the range, UTC generation, policy, coverage, and exact integers. A blank cell is unknown; 0 is a measured zero. Import IDs and large integers as text in your spreadsheet to preserve digits.

The GET /v1/usage/export.csv and /video/v1/usage/export.csv routes accept a period, asset, and schema; they do not accept page or limit. Each export uses a PostgreSQL snapshot, rather than assembling pages from different moments. The response is UTF-8 CSV with BOM, CRLF, and quoted fields; text with formula prefixes receives a protective apostrophe. The SDK’s Fetch decoder may remove the BOM.

Limits and interpretation

Up to 10,000 assets and 20 MiB per CSV; exceeding either returns 413 before the attachment. Queries have population budgets and five seconds per SQL statement; timeout returns 503. A truncated export is never presented as complete. If required auxiliary data is missing, v3 fails without silently reducing the schema.

Delivery/ingest receipts are retained for 90 days. Ingest durations are attributed to acceptance time, even if confirmed later; they are not the normalized asset duration. For HLS imports, ingest bytes are downloaded bodies, rather than remux size. Deleting an asset preserves historical attribution; deleting the environment removes its data.

Usage is not an invoice. Rates, versioned costs, and cost attribution remain outstanding. It also differs from playback analytics and their daily view exports.