---
title: "Report a use of a video moment (network)"
method: POST
path: "/public/usage"
---

# Report a use of a video moment (network)

`POST /public/usage`

## Request

- Base URL: `https://api.agentcdn.com`
- URL: `https://api.agentcdn.com/public/usage`
- Auth: none declared

record_usage over REST. Reports that a moment was used and returns a signed receipt. The use is checked against the rights policy in force: a permitted use is recorded on the usage ledger, and a refused use is logged as refused and is never counted as a use. The video must be public and its creator listed on the network. Any range of a published video is accepted.

## Request body

- UsageReport
  - `moment_uri` string: String arv:{asset_id}#t={start_ms},{end_ms}. Copy it from a search result. A value of another shape answers 400 moment_invalid.
  - `moment_id` string: String. The moment id from a search result. Send it with the range as a cross-check. It cannot name a moment alone. A value of another shape answers 400 moment_invalid.
  - `asset_id` string: String. A video id. Use with start_ms and end_ms to report any range on a published video. A value of another shape answers 400 moment_invalid.
  - `start_ms` integer: Whole number. Range start in milliseconds. A value of another shape answers 400 moment_invalid.
  - `end_ms` integer: Whole number. Range end in milliseconds. A value of another shape answers 400 moment_invalid.
  - `action` string, required: What the agent did with the moment: one term of the RightsSummary, for example cite, quote or segment_display. A term the rights do not define is refused. A term the rights policy does not define answers 403 action_not_permitted.
  - `served_to` object: Who the moment was served to: the agent name and the surface, for example chatgpt and chat.
    - `agent` string, required
    - `surface` string
  - `idempotency_key` string: Up to 128 characters A-Z, a-z, 0-9, dot, underscore, colon or hyphen, for example a UUID. Send a new key for each separate use and the same key when you retry. A repeat within the same UTC hour returns the original receipt.

## Response `200`

A signed UsageReceipt (ARV 1.0 section 3.5). Verify `jws` with the manifest's jwks_url.

- UsageReceipt
  - `arv` '1.0', required
  - `receipt_id` string, required
  - `moment_uri` string, required
  - `moment_id` string, required
  - `action` string, required
  - `served_to` object, required
    - `agent` string, required
    - `surface` string
  - `policy_version` integer, required
  - `served_at` string, required
  - `citation` string
  - `jws` string, required
  - `payment_ref` string
  - `entitlement_ref` string

## Other responses

- `400`: The body was not a usage request (not an object, an unknown member, a missing or malformed action, a malformed served_to, or a malformed idempotency_key), or the moment was malformed, missing, outside the video, or its moment_id did not match. Error codes: invalid_request, moment_invalid.
- `403`: The rights policy does not permit the use, or the quote is longer than the limit. Error codes: action_not_permitted, quote_over_limit.
- `404`: Unknown creator, or no public video with that id. Error codes: creator_not_found, asset_not_found.
- `429`: Rate limited. Retry after the retry-after header (seconds). Error codes: agent_rate_limited.
- `503`: Nothing was recorded and no receipt was issued. Error codes: usage_ledger_unavailable, receipt_signing_unavailable, rights_policy_lookup_unavailable.

---

[API](https://skmtc.dev/agentcdn/apis/agentcdn-public-arv-api.md) · [All operations](https://skmtc.dev/agentcdn/apis/agentcdn-public-arv-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentcdn/apis/agentcdn-public-arv-api/revisions/a86951be4158?raw)