Sign in
asset-reference-usage

Rank edit reference assets used by organization requests

Changed on

Counts completed requests made by the authenticated organization that used each existing asset as an edit input during the UTC date range. Direct file uploads without saved asset identifiers are excluded. Results are independent of current asset ownership, collection membership, and sharing. Returning an identifier does not grant access to its image. Tracking begins when enabled; earlier history is not included. Returns 50 assets per page by default, up to 100 with limit. Rankings may change between pages when daily counts are updated; cursors do not pin a historical snapshot.

get/v2/assets/reference-usage

Request

  • Base URL: (relative, and it does not resolve against the document’s source URL)
  • URL: /v2/assets/reference-usage
  • Auth: one of:
    • API key in header Api-Key
    • HTTP bearer

Query parameters

limitinteger

Maximum number of returned entries per page.

collection_idsstring[]

Exact collections to rank within; requires include_collections=true. Includes direct members only, not descendants. Every collection must be accessible. Counts include only completed requests that explicitly selected the asset from that collection. Keep the same selection on every cursor page.

include_collectionsboolean

Return one entry per explicitly referenced collection asset, with its collection-specific usage count and current filename and attributes. Only currently accessible members are returned. Pages may be short or empty; follow next_cursor until null.

start_datestring date required

Inclusive UTC usage date.

end_datestring date required

Exclusive UTC usage date, later than start_date.

cursorstring

Opaque next-page cursor. Keep the same date range on every page.

Response

Ranked edit reference assets

next_cursorstring nullable required

Example response

{
  "next_cursor": "next_cursor",
  "assets": [
    {
      "collection_id": "collection_id",
      "collection_path": "collection_path",
      "asset_identifier": {
        "asset_type": "RESPONSE",
        "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
      },
      "file_name": "file_name",
      "download_url": "download_url",
      "attributes": [
        {
          "creation_time": "2000-01-23T04:56:07+00:00",
          "value_type": null,
          "attribute_key": "attribute_key",
          "value": "value"
        },
        {
          "creation_time": "2000-01-23T04:56:07+00:00",
          "value_type": null,
          "attribute_key": "attribute_key",
          "value": "value"
        }
      ],
      "collection_name": "collection_name",
      "request_count": 1
    },
    {
      "collection_id": "collection_id",
      "collection_path": "collection_path",
      "asset_identifier": {
        "asset_type": "RESPONSE",
        "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
      },
      "file_name": "file_name",
      "download_url": "download_url",
      "attributes": [
        {
          "creation_time": "2000-01-23T04:56:07+00:00",
          "value_type": null,
          "attribute_key": "attribute_key",
          "value": "value"
        },
        {
          "creation_time": "2000-01-23T04:56:07+00:00",
          "value_type": null,
          "attribute_key": "attribute_key",
          "value": "value"
        }
      ],
      "collection_name": "collection_name",
      "request_count": 1
    }
  ]
}

Changes

  • 919a744eb885Revision changes
    • ○

      added the new optional query request parameter collection_ids

    • ○

      added the new optional query request parameter limit

    • ○

      added the optional property /// to the response with the status

    • ○

      added the optional property // to the response with the status

  • e6fd9b41990eRevision changes
    • ○

      added the new optional query request parameter include_collections

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status

    • ○

      added the optional property // to the response with the status