get_usage_summary
Workspace Analytics & Billing: the RUNS of ONE Enterprise workspace (the same runs as list_generation_events, so its rows added up equal these totals) added up per group. Needs a workspace reporting key (wdr_report_…, made by the workspace Owner) for that workspace, or your own sign-in as its Owner or Admin (every run) or Member (only your own runs). group_by: any of day, week (its Monday), month (YYYY-MM) — cut in Asia/Ho_Chi_Minh — user, team, project, app, model, feature, channel, output_kind, duration_bucket, requested_duration_bucket, resolution, aspect_ratio, status; none = one row for the whole range. Each row: the group's fields (date, week, month, user_id + email, team ("unclassified" = no team; a person's team when the run finished, so a team change splits at that moment), project_id, app_name, model_id + model_name, feature, channel, output_kind, duration_bucket, requested_duration_bucket, resolution, aspect_ratio, status — as in list_generation_events), then: OUTPUT, on the day a run finished (still running: the day it was sent): attempts (runs; a retry is a new run), succeeded, failed, running (still in progress), outputs_image / outputs_video / outputs_audio (files made), gross_debit_credits, refunded_credits, net_credits (= gross − refunded; a run's refund counts with the run even when posted another day), reserved_credits (still held by runs in progress), cost_effective_usd (the runs' net × meta.cost_basis.effective_cents_per_credit, the workspace's one effective price; null when it has none) and cost_list_usd (1 credit = $0.01); queue_time_seconds (started − sent), generation_time_seconds (finished − started), request_to_result_seconds (finished − sent), each {avg, p50, p90, n, n_approximate}: per run, never parallel runs added together; p50 / p90 nearest-rank within the group; n = runs measured (runs still going are left out: they are in running), n_approximate = how many of them were timed from an approximate start; no sample ⇒ avg / p50 / p90 null, never 0. USE, on the day a run was SENT: active_users (people who sent ≥ 1 run), days_used (days with ≥ 1 run sent, free runs included), days_with_spend (days with ≥ 1 run sent that cost credits), last_used_day (rows per person: their last such day in the range; null = none). approved_creatives: Drama Studio only (the one studio with an approval step: an edit or a film a producer approved), on the day it was approved, for the editor who submitted it (else the approver); every other studio has no approved state yet (meta.missing_fields). Filters (user_id, team, project_id, app, model_id, feature, channel, output_kind, duration_bucket, requested_duration_bucket, resolution, status) work as in list_generation_events: only the matching runs are added up. Grouped by user or team, everyone who belonged to the workspace on a day of the range gets a row, with zeros when they did nothing. The credit ledger by the day each movement was posted is list_credit_transactions, a different view: do not mix the two. compare_previous=true adds the same rows for the window of the same length just before, with window = "previous" (and window = "current" on the others). from (first day, included) and to (the day after the last, excluded), YYYY-MM-DD in Asia/Ho_Chi_Minh, at most 366 days; default the last 30 days including today. Paging: up to limit rows (1–1,000, default 1,000); when meta.next_cursor is not null pass it as cursor (same arguments) for the next page. Free; at most 60 calls a minute per key or person. CSV: GET /api/v1/workspaces/{workspace_id}/reports/get_usage_summary?format=csv&group_by=day,user.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | The day after the last, excluded (YYYY-MM-DD, Asia/Ho_Chi_Minh). Default: tomorrow. At most 366 days after `from`. | |
| app | No | Only runs of this app (app_name: the Cinematic Ads project's app name). | |
| from | No | First day, included (YYYY-MM-DD, Asia/Ho_Chi_Minh). Default: 30 days before `to`. | |
| team | No | Only runs of this team, as the report names it ("unclassified" = people with no team). | |
| limit | No | Rows per page. | |
| cursor | No | meta.next_cursor of the previous page, unchanged. | |
| status | No | Only runs in this state. | |
| channel | No | Only runs that came this way. | |
| feature | No | Only runs of this feature (a feature from list_services, or what a step outside jobs was charged for: cinematic_ads_analysis, cinematic_ads_ai, cinematic_ads_export, drama_chat, …). | |
| user_id | No | Only this person's runs (a user id from list_workspace_members). | |
| group_by | No | The dimensions of a row, e.g. ["day", "user"]. None = one row for the whole range. | |
| model_id | No | Only runs of this model (a model_id from list_services; older names of the same model are included). | |
| project_id | No | Only runs of this project (a Cinematic Ads or Drama Studio project id). | |
| resolution | No | Only videos of this measured resolution, e.g. 720p (the shorter side in pixels). | |
| output_kind | No | Only runs making this kind of output. | |
| workspace_id | Yes | The workspace: the one the reporting key belongs to, or one you are a member of. | |
| duration_bucket | No | Only videos whose measured length is in this bucket. | |
| compare_previous | No | Also return the window of the same length just before (rows with window = "previous"). | |
| requested_duration_bucket | No | Only videos whose requested length is in this bucket. |