API reference

Analytics

Every path is under https://impartire.com/api/v1. Generated from the API’s own contract, openapi.json (OpenAPI 3.1), which you can load into any OpenAPI tool. Errors are Problems — see Conventions.

GET/api/v1/analytics/summary

Read consumption analytics over a range

The numbers of the app's analytics dashboard: views, unique viewers, playback time and downloads over range reporting days ending today (the org's reporting day — its time zone and start hour — not a UTC calendar day), the same over the range before it, one point per day, the ten most viewed assets, and the device and audience breakdowns. viewer_type filters to one audience (api — developer-API downloads). Reading it first materializes every reporting day that has ended into the rollup, as the app's dashboard does (a write of derived data only). Channel audience is not served. For an OAuth token, its person needs membership of the org (no platform-admin bypass) and an asset's name is null when they may not read the asset; a key reads the whole org. 404 when the org does not have analytics, and for an OAuth token whose person is not a member of the org.

Scopes: analytics:read

Parameters

rangequery · "7d" | "30d" | "90d" | "365d"
How many reporting days, today included. Default 30d.
viewer_typequery · "all" | "internal" | "consumer" | "embed" | "api"
Filter to one audience. Default all.

Response 200ConsumptionAnalytics

How the org's content was consumed over a range: the numbers of the app's analytics dashboard.

rangeobjectrequired
- fromstring (date)required
  The first reporting day of the range (YYYY-MM-DD).
- tostring (date)required
  The last reporting day of the range (YYYY-MM-DD), today included.
reporting_dayobjectrequired
The org's reporting day: every day, range and bucket here is one of these, not a UTC calendar day.
- timezonestringrequired
  The org's reporting-day time zone (IANA).
- day_start_hourintegerrequired
  The hour (0–23, in that zone) a reporting day starts — a broadcaster's day may start at 06:00.
viewer_type"all" | "internal" | "consumer" | "embed" | "api"required
The audience the figures are filtered to (all — none). by_viewer_type ignores it.
summaryAnalyticsTotalsrequired
Consumption totals over a range.
- total_viewsintegerrequired
  Views: a surface that renders the asset was opened (once per session and asset).
- unique_viewersintegerrequired
  Distinct viewers over the whole range — exact, not a sum of daily uniques.
- total_playback_msintegerrequired
  Milliseconds of playback watched.
- total_downloadsintegerrequired
  Downloads: the bytes were taken.
previous_periodobjectrequired
The same totals over the range of equal length ending the day before range.from.
- total_viewsintegerrequired
  Views: a surface that renders the asset was opened (once per session and asset).
- unique_viewersintegerrequired
  Distinct viewers over the whole range — exact, not a sum of daily uniques.
- total_playback_msintegerrequired
  Milliseconds of playback watched.
- total_downloadsintegerrequired
  Downloads: the bytes were taken.
- fromstring (date)required
- tostring (date)required
seriesarray of objectrequired
One point per reporting day of the range, oldest first, zero-filled.
- daystring (date)required
- viewsintegerrequired
- unique_viewersintegerrequired
  Distinct viewers that day.
- watched_msintegerrequired
- downloadsintegerrequired
top_assetsarray of objectrequired
The ten most viewed assets of the range (every version of an asset counts toward it), most viewed first.
- assetobjectrequired
  - idstring (uuid)required
    The asset's current version id (GET /api/v1/assets/{id}).
  - namestring or nullrequired
    The asset's name. Null — for an OAuth token — when its person may not read the asset: the figures are org figures every member sees on the dashboard; the name is not disclosed.
- viewsintegerrequired
- downloadsintegerrequired
by_devicearray of objectrequired
Views, downloads and playback sessions together, by device, largest first.
- device_typestringrequired
  desktop, mobile, tablet or unknown.
- countintegerrequired
by_viewer_typearray of objectrequired
Views, downloads and playback sessions together, by audience, largest first — over every audience, whatever viewer_type is.
- viewer_typestringrequired
  internal (a member), consumer, embed (a share link) or api (a developer-API download).
- countintegerrequired

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
422 validation — a bad range or viewer_type (errors[].path names it).
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

GET/api/v1/analytics/operations

Read operations analytics over a range

The numbers of the app's operations view over range reporting days ending today: workflow runs started, completed, failed and open, with durations; approvals and their latency; open incidents; delivery attempts, outcomes and latency; assets created, time to first approval, and the assets nobody opened. workflows.active and incidents.active are true now, not range figures. For an OAuth token, its person needs membership of the org (no platform-admin bypass) and an asset's name is null when they may not read the asset; a key reads the whole org. 404 when the org does not have analytics, and for an OAuth token whose person is not a member of the org.

Scopes: analytics:read

Parameters

rangequery · "7d" | "30d" | "90d" | "365d"
How many reporting days, today included. Default 30d.

Response 200OperationsAnalytics

How the DAM was operated over a range — runs, approvals, incidents, deliveries, assets: the numbers of the app's operations view.

rangeobjectrequired
- fromstring (date)required
  The first reporting day of the range (YYYY-MM-DD).
- tostring (date)required
  The last reporting day of the range (YYYY-MM-DD), today included.
reporting_dayobjectrequired
The org's reporting day: every day, range and bucket here is one of these, not a UTC calendar day.
- timezonestringrequired
  The org's reporting-day time zone (IANA).
- day_start_hourintegerrequired
  The hour (0–23, in that zone) a reporting day starts — a broadcaster's day may start at 06:00.
workflowsobjectrequired
- startedintegerrequired
  Runs started in the range.
- completedintegerrequired
  Runs that completed in the range (dated by when they ended).
- failedintegerrequired
- cancelledintegerrequired
- activeintegerrequired
  Runs open right now, whenever they started.
- duration_p50_msinteger or nullrequired
  Median start-to-completion time of the runs completed in the range; null when none.
- duration_p90_msinteger or nullrequired
approvalsobjectrequired
- submittedintegerrequired
- approvedintegerrequired
- latency_p50_msinteger or nullrequired
  Median submit-to-approve time of the approvals given in the range; null when none.
- latency_p90_msinteger or nullrequired
incidentsobjectrequired
- activeintegerrequired
  Run steps parked for an operator right now.
deliveriesobjectrequired
- attemptedintegerrequired
  Deliveries attempted in the range; delivered and failed count how those turned out (the rest are pending).
- deliveredintegerrequired
- failedintegerrequired
- success_ratenumber or nullrequired
  delivered / attempted, 0–1; null when nothing was attempted.
- latency_p50_msinteger or nullrequired
assetsobjectrequired
- createdintegerrequired
- time_to_first_approval_p50_msinteger or nullrequired
  Median time from an asset's creation to its first approval, over first approvals given in the range.
- unconsumedobjectrequired
  - countintegerrequired
    Assets that existed when the range opened and were not viewed, downloaded or played during it.
  - samplearray of objectrequired
    Up to ten of them, newest first.
    - assetobjectrequired
      - idstring (uuid)required
        The asset's current version id (GET /api/v1/assets/{id}).
      - namestring or nullrequired
        The asset's name. Null — for an OAuth token — when its person may not read the asset: the figures are org figures every member sees on the dashboard; the name is not disclosed.
    - created_atstring (date-time)required
seriesarray of objectrequired
One point per reporting day of the range, oldest first, zero-filled.
- daystring (date)required
- workflows_completedintegerrequired
- deliveries_deliveredintegerrequired

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
422 validation — a bad range.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

GET/api/v1/analytics/search

Read search analytics over a range

The numbers of the app's search view over range reporting days ending today: asset searches, those that found nothing, unique searchers, the same over the range before it, one point per day, and the top queries and top zero-result queries. For an OAuth token, its person needs membership of the org (no platform-admin bypass) and an asset's name is null when they may not read the asset; a key reads the whole org. 404 when the org does not have analytics, and for an OAuth token whose person is not a member of the org.

Scopes: analytics:read

Parameters

rangequery · "7d" | "30d" | "90d" | "365d"
How many reporting days, today included. Default 30d.

Response 200SearchAnalytics

What people searched the asset library for, and did not find, over a range: the numbers of the app's search view.

rangeobjectrequired
- fromstring (date)required
  The first reporting day of the range (YYYY-MM-DD).
- tostring (date)required
  The last reporting day of the range (YYYY-MM-DD), today included.
reporting_dayobjectrequired
The org's reporting day: every day, range and bucket here is one of these, not a UTC calendar day.
- timezonestringrequired
  The org's reporting-day time zone (IANA).
- day_start_hourintegerrequired
  The hour (0–23, in that zone) a reporting day starts — a broadcaster's day may start at 06:00.
summarySearchTotalsrequired
Asset-search totals over a range.
- searchesintegerrequired
- zero_result_searchesintegerrequired
- unique_searchersintegerrequired
previous_periodobjectrequired
The same totals over the range of equal length ending the day before range.from.
- searchesintegerrequired
- zero_result_searchesintegerrequired
- unique_searchersintegerrequired
- fromstring (date)required
- tostring (date)required
seriesarray of objectrequired
One point per reporting day, oldest first, zero-filled.
- daystring (date)required
- searchesintegerrequired
- zero_resultsintegerrequired
top_queriesarray of objectrequired
The 20 most frequent queries.
- querystringrequired
- searchesintegerrequired
- avg_resultsnumberrequired
  Mean result count, one decimal.
zero_result_queriesarray of objectrequired
The 20 most frequent queries that found nothing.
- querystringrequired
- searchesintegerrequired

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
422 validation — a bad range.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.