Application Launcher

The Acquia DAM API v2 provides programmatic access to raw interaction event logs. You can query granular interaction events across assets, collections, embeds, and user sessions to integrate analytics data into business intelligence tools, data warehouses, or external reporting dashboards.

Endpoint overview

HTTP Method: POST
Path: /v2/analytics/events/query
Content-Type: application/json
Authentication: Bearer Token (OAuth 2.0)
Feature Flag: Requires the global-api-insights feature toggle enabled on your account. If this feature toggle is disabled, requests return an HTTP 404 Not Found response status.

Authentication and permissions

To query event records, your API token or user account must have both of the following permissions enabled:

Access Insights permission (ANALYTICS_ACCESS)
Export Analytics Reports permission (EXPORT_ASSET_ANALYTICS)

If either permission is missing from your account role, the API returns an HTTP 403 Forbidden response status with the message: "User does not have permission to access query analytics". For more information on role configuration, refer to the Acquia DAM User Permissions Documentation.

Request headers

Header	Type	Description	Required
Authorization	string	OAuth 2.0 Bearer token format: Bearer <access_token>.	Yes
Content-Type	string	Must be set to application/json.	Yes

Request body schema

The request payload accepts the following properties:

Field	Type	Description	Required
event_type	string	The event type to query. Must be one of the nine supported event types.	Yes
start_date	string	ISO 8601 UTC timestamp (for example, 2026-08-01T00:00:00Z). Must be in three years of the current date.	Yes
end_date	string	ISO 8601 UTC timestamp (for example, 2026-08-31T23:59:59Z). Must be in three years of the current date and must not precede start_date.	Yes
fields	array of strings	Specific field names to return in the response. Omit this property to return all standard public fields for the specified event type.	No
filters	array of objects	Filter criteria to narrow event results. Multiple filter objects in the array are combined with AND logic.	No
limit	integer	The maximum number of event records to return in a single page. Default is 100; maximum allowed value is 10000.

Filter object structure

When supplying objects in the filters array:

{
  "type": "file_format",
  "operator": "equals",
  "values": [
    "JPEG",
    "PNG"
  ]
}

Property	Type	Description	Required
type	string	The filter identifier. Must match a supported filter type for the selected event_type.	Yes
operator	string	The comparison operator. Must be equals for all filters, except search_results_count on asset_search which also accepts greaterThan and lessThan.	Yes
values	array of strings	One or more values to match. Multiple values supplied in the array are evaluated with OR logic.	Yes

Supported event types and filterable fields

Each of the nine supported event types accepts a distinct set of filter types:

Event Type (event_type)	Description	Supported Filter type Values	Notes
download	Asset file downloads	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, intended_use, metadata_type_uuid, portal, source, user_uuid, user_external_id, user_role_uuid	source accepts: order, portal, api. country and state_or_region expect full names, not ISO codes.
asset_view	Asset detail and preview views	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, metadata_type_uuid, user_uuid, user_external_id, user_role_uuid, view_location	view_location accepts: dam, asset_digest, portal, quickview.
embed_view	Impressions on published embed links	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, metadata_type_uuid, embed_link_creator_user_uuid, embed_link_creator_user_external_id, embed_link_creator_role_uuid, view_location	Uses embed_link_creator_* filters instead of standard user filters. view_location returns embed.
share	Individual asset sharing	asset_uuid, asset_external_id, city, state_or_region, country, share_by_user_uuid, share_by_user_external_id, share_recipient

Request example

The following example queries download events for PDF and PNG files occurring in August 2026:

curl -X POST "https://api.widen.net/v2/analytics/events/query" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "download",
    "start_date": "2026-08-01T00:00:00Z",
    "end_date": "2026-08-31T23:59:59Z",
    "fields": [
      "event_id",
      "timestamp",
      "asset_id",
      "filename",
      "file_format",
      "user_email"
    ],
    "filters": [
      {
        "type": "file_format",
        "operator": "equals",
        "values": ["JPEG", "PNG"]
      }
    ],
    "limit": 5000
  }'

Response structure and example

Response properties

total_results (integer): Total number of events matching the query criteria across all pages.
pagination_token (string or null): Opaque pagination cursor. Returns null when no further records remain.
events (array of objects): Array of flat key-value maps representing each event record.

Response example (HTTP 200 OK)

{
  "total_results": 1420,
  "pagination_token": "eyJleGNsdXNpdmVTdGFydEtleSI6IjEyMzQ1NiJ9",
  "events": [
    {
      "event_id": "08f85f61-6a8a-438e-91ae-8e22a875b402",
      "timestamp": "2026-08-15T14:22:18Z",
      "asset_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "filename": "brand_guidelines_2026.pdf",
      "file_format": "pdf",
      "user_email": "[email protected]"
    }
  ]
}

Pagination workflow

Submit the initial POST request with required parameters (event_type, start_date, and end_date).
Read pagination_token in the response payload.
If pagination_token is present and non-null, submit the subsequent POST request with identical query parameters and pass pagination_token.
Continue until pagination_token returns null.

HTTP status codes

Status Code	Status Name	Description
200 OK	Success	The query completed successfully and returned matching events.
400 Bad Request	Invalid Request	Missing required parameters (event_type, start_date, end_date), date outside the allowed three-year boundary, or invalid filter configuration.
401 Unauthorized	Authentication Failed	Missing, invalid, or expired Bearer access token.
403 Forbidden	Permission Denied	Caller lacks either the Access Insights permission or the Export Analytics Reports permission.
404 Not Found	Feature Disabled	The global-api-insights feature toggle is disabled for the account.
429 Too Many Requests	Rate Limit Exceeded	Request volume exceeded rate limits. Retry requests according to the Retry-After header.
500 Internal Server Error	Server Error	An unexpected error occurred. Contact Acquia Support if the issue persists.

Endpoint overview

HTTP Method: POST
Path: /v2/analytics/events/query
Content-Type: application/json
Authentication: Bearer Token (OAuth 2.0)
Feature Flag: Requires the global-api-insights feature toggle enabled on your account. If this feature toggle is disabled, requests return an HTTP 404 Not Found response status.

Authentication and permissions

To query event records, your API token or user account must have both of the following permissions enabled:

Access Insights permission (ANALYTICS_ACCESS)
Export Analytics Reports permission (EXPORT_ASSET_ANALYTICS)

Request headers

Endpoint overview

HTTP Method: POST
Path: /v2/analytics/events/query
Content-Type: application/json
Authentication: Bearer Token (OAuth 2.0)
Feature Flag: Requires the global-api-insights feature toggle enabled on your account. If this feature toggle is disabled, requests return an HTTP 404 Not Found response status.

Authentication and permissions

To query event records, your API token or user account must have both of the following permissions enabled:

Access Insights permission (ANALYTICS_ACCESS)
Export Analytics Reports permission (EXPORT_ASSET_ANALYTICS)

Request headers

Header	Type	Description	Required
Authorization	string	OAuth 2.0 Bearer token format: Bearer <access_token>.	Yes
Content-Type	string	Must be set to application/json.	Yes

Request body schema

The request payload accepts the following properties:

Field	Type	Description	Required
event_type	string	The event type to query. Must be one of the nine supported event types.	Yes
start_date	string	ISO 8601 UTC timestamp (for example, 2026-08-01T00:00:00Z). Must be in three years of the current date.	Yes
end_date	string	ISO 8601 UTC timestamp (for example, 2026-08-31T23:59:59Z). Must be in three years of the current date and must not precede start_date.	Yes
fields	array of strings	Specific field names to return in the response. Omit this property to return all standard public fields for the specified event type.	No
filters	array of objects	Filter criteria to narrow event results. Multiple filter objects in the array are combined with AND logic.	No
limit	integer	The maximum number of event records to return in a single page. Default is 100; maximum allowed value is 10000.

Filter object structure

When supplying objects in the filters array:

{
  "type": "file_format",
  "operator": "equals",
  "values": [
    "JPEG",
    "PNG"
  ]
}

Property	Type	Description	Required
type	string	The filter identifier. Must match a supported filter type for the selected event_type.	Yes
operator	string	The comparison operator. Must be equals for all filters, except search_results_count on asset_search which also accepts greaterThan and lessThan.	Yes
values	array of strings	One or more values to match. Multiple values supplied in the array are evaluated with OR logic.	Yes

Supported event types and filterable fields

Each of the nine supported event types accepts a distinct set of filter types:

Event Type (event_type)	Description	Supported Filter type Values	Notes
download	Asset file downloads	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, intended_use, metadata_type_uuid, portal, source, user_uuid, user_external_id, user_role_uuid	source accepts: order, portal, api. country and state_or_region expect full names, not ISO codes.
asset_view	Asset detail and preview views	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, metadata_type_uuid, user_uuid, user_external_id, user_role_uuid, view_location	view_location accepts: dam, asset_digest, portal, quickview.
embed_view	Impressions on published embed links	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, metadata_type_uuid, embed_link_creator_user_uuid, embed_link_creator_user_external_id, embed_link_creator_role_uuid, view_location	Uses embed_link_creator_* filters instead of standard user filters. view_location returns embed.
share	Individual asset sharing	asset_uuid, asset_external_id, city, state_or_region, country, share_by_user_uuid, share_by_user_external_id, share_recipient

Request example

The following example queries download events for PDF and PNG files occurring in August 2026:

curl -X POST "https://api.widen.net/v2/analytics/events/query" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "download",
    "start_date": "2026-08-01T00:00:00Z",
    "end_date": "2026-08-31T23:59:59Z",
    "fields": [
      "event_id",
      "timestamp",
      "asset_id",
      "filename",
      "file_format",
      "user_email"
    ],
    "filters": [
      {
        "type": "file_format",
        "operator": "equals",
        "values": ["JPEG", "PNG"]
      }
    ],
    "limit": 5000
  }'

Response structure and example

Response properties

total_results (integer): Total number of events matching the query criteria across all pages.
pagination_token (string or null): Opaque pagination cursor. Returns null when no further records remain.
events (array of objects): Array of flat key-value maps representing each event record.

Response example (HTTP 200 OK)

{
  "total_results": 1420,
  "pagination_token": "eyJleGNsdXNpdmVTdGFydEtleSI6IjEyMzQ1NiJ9",
  "events": [
    {
      "event_id": "08f85f61-6a8a-438e-91ae-8e22a875b402",
      "timestamp": "2026-08-15T14:22:18Z",
      "asset_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "filename": "brand_guidelines_2026.pdf",
      "file_format": "pdf",
      "user_email": "[email protected]"
    }
  ]
}

Pagination workflow

Submit the initial POST request with required parameters (event_type, start_date, and end_date).
Read pagination_token in the response payload.
If pagination_token is present and non-null, submit the subsequent POST request with identical query parameters and pass pagination_token.
Continue until pagination_token returns null.

HTTP status codes

Status Code	Status Name	Description
200 OK	Success	The query completed successfully and returned matching events.
400 Bad Request	Invalid Request	Missing required parameters (event_type, start_date, end_date), date outside the allowed three-year boundary, or invalid filter configuration.
401 Unauthorized	Authentication Failed	Missing, invalid, or expired Bearer access token.
403 Forbidden	Permission Denied	Caller lacks either the Access Insights permission or the Export Analytics Reports permission.
404 Not Found	Feature Disabled	The global-api-insights feature toggle is disabled for the account.
429 Too Many Requests	Rate Limit Exceeded	Request volume exceeded rate limits. Retry requests according to the Retry-After header.
500 Internal Server Error	Server Error	An unexpected error occurred. Contact Acquia Support if the issue persists.

Header	Type	Description	Required
Authorization	string	OAuth 2.0 Bearer token format: Bearer <access_token>.	Yes
Content-Type	string	Must be set to application/json.	Yes

Field	Type	Description	Required
event_type	string	The event type to query. Must be one of the nine supported event types.	Yes
start_date	string	ISO 8601 UTC timestamp (for example, 2026-08-01T00:00:00Z). Must be in three years of the current date.	Yes
end_date	string	ISO 8601 UTC timestamp (for example, 2026-08-31T23:59:59Z). Must be in three years of the current date and must not precede start_date.	Yes
fields	array of strings	Specific field names to return in the response. Omit this property to return all standard public fields for the specified event type.	No
filters	array of objects	Filter criteria to narrow event results. Multiple filter objects in the array are combined with AND logic.	No
limit	integer	The maximum number of event records to return in a single page. Default is 100; maximum allowed value is 10000.	No
pagination_token	string	Opaque cursor token received from a previous response to retrieve the subsequent page.	No

Property	Type	Description	Required
type	string	The filter identifier. Must match a supported filter type for the selected event_type.	Yes
operator	string	The comparison operator. Must be equals for all filters, except search_results_count on asset_search which also accepts greaterThan and lessThan.	Yes
values	array of strings	One or more values to match. Multiple values supplied in the array are evaluated with OR logic.	Yes

Event Type (event_type)	Description	Supported Filter type Values	Notes
download	Asset file downloads	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, intended_use, metadata_type_uuid, portal, source, user_uuid, user_external_id, user_role_uuid	source accepts: order, portal, api. country and state_or_region expect full names, not ISO codes.
asset_view	Asset detail and preview views	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, metadata_type_uuid, user_uuid, user_external_id, user_role_uuid, view_location	view_location accepts: dam, asset_digest, portal, quickview.
embed_view	Impressions on published embed links	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, collection_uuid, collection_external_id, city, state_or_region, country, file_format, file_type, metadata_type_uuid, embed_link_creator_user_uuid, embed_link_creator_user_external_id, embed_link_creator_role_uuid, view_location	Uses embed_link_creator_* filters instead of standard user filters. view_location returns embed.
share	Individual asset sharing	asset_uuid, asset_external_id, city, state_or_region, country, share_by_user_uuid, share_by_user_external_id, share_recipient	share_recipient filters by recipient email.
collection_share	Collection sharing events	collection_uuid, collection_external_id, country, state_or_region, share_by_user_uuid, share_by_user_external_id, share_recipient	Collection-scoped; does not support asset filters.
asset_upload	Asset file uploads	asset_uuid, asset_external_id, asset_group_uuid, category_uuid, city, state_or_region, country, file_format, file_type, metadata_type_uuid, upload_profile_uuid, upload_source, user_uuid, user_external_id, user_role_uuid	upload_source accepts: dam, rest_api, ftp. Does not support collection filters.
login	User authentication sessions	city, state_or_region, country, login_type, user_uuid, user_external_id, user_role_uuid	login_type accepts: SITE.
portal_view	Brand portal access events	city, country, state_or_region, portal, portal_access_code_email, user_uuid, user_external_id, user_role_uuid	portal matches portal external ID; portal_access_code_email filters visitor email.
asset_search	Search operations executed in DAM	city, country, state_or_region, search_category_uuid, search_location, search_name, search_results_count, search_type, user_uuid, user_external_id, user_role_uuid	search_location accepts: assets, dam, api. search_type accepts: keyword, suggested. search_results_count supports equals, greaterThan, and lessThan.

curl -X POST "https://api.widen.net/v2/analytics/events/query" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "download",
    "start_date": "2026-08-01T00:00:00Z",
    "end_date": "2026-08-31T23:59:59Z",
    "fields": [
      "event_id",
      "timestamp",
      "asset_id",
      "filename",
      "file_format",
      "user_email"
    ],
    "filters": [
      {
        "type": "file_format",
        "operator": "equals",
        "values": ["JPEG", "PNG"]
      }
    ],
    "limit": 5000
  }'

{
  "total_results": 1420,
  "pagination_token": "eyJleGNsdXNpdmVTdGFydEtleSI6IjEyMzQ1NiJ9",
  "events": [
    {
      "event_id": "08f85f61-6a8a-438e-91ae-8e22a875b402",
      "timestamp": "2026-08-15T14:22:18Z",
      "asset_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "filename": "brand_guidelines_2026.pdf",
      "file_format": "pdf",
      "user_email": "[email protected]"
    }
  ]
}

Status Code	Status Name	Description
200 OK	Success	The query completed successfully and returned matching events.
400 Bad Request	Invalid Request	Missing required parameters (event_type, start_date, end_date), date outside the allowed three-year boundary, or invalid filter configuration.
401 Unauthorized	Authentication Failed	Missing, invalid, or expired Bearer access token.
403 Forbidden	Permission Denied	Caller lacks either the Access Insights permission or the Export Analytics Reports permission.
404 Not Found	Feature Disabled	The global-api-insights feature toggle is disabled for the account.
429 Too Many Requests	Rate Limit Exceeded	Request volume exceeded rate limits. Retry requests according to the Retry-After header.
500 Internal Server Error	Server Error	An unexpected error occurred. Contact Acquia Support if the issue persists.

Endpoint overview

Authentication and permissions

Request headers

Request body schema

Filter object structure

Supported event types and filterable fields

Request example

Response structure and example

Response properties

Response example (HTTP 200 OK)

HTTP status codes

Endpoint overview

Authentication and permissions

Request headers

Endpoint overview

Authentication and permissions

Request headers

Request body schema

Filter object structure

Supported event types and filterable fields

Request example

Response structure and example

Response properties

Response example (HTTP 200 OK)

HTTP status codes

Request body schema

Filter object structure

Supported event types and filterable fields

Request example

Response structure and example

Response properties

Response example (HTTP 200 OK)

HTTP status codes

Did not find what you were looking for?

Did not find what you were looking for?

Querying analytics and insights events with the Acquia DAM API v2

Endpoint overview

Authentication and permissions

Request headers

Request body schema

Filter object structure

Supported event types and filterable fields

Request example

Response structure and example

Response properties

Response example (HTTP 200 OK)

Pagination workflow

HTTP status codes

Querying analytics and insights events with the Acquia DAM API v2

Endpoint overview

Authentication and permissions

Request headers

Querying analytics and insights events with the Acquia DAM API v2

Endpoint overview

Authentication and permissions

Request headers

Request body schema

Filter object structure

Supported event types and filterable fields

Request example

Response structure and example

Response properties

Response example (HTTP 200 OK)

Pagination workflow

HTTP status codes

Request body schema

Filter object structure

Supported event types and filterable fields

Request example

Response structure and example

Response properties

Response example (HTTP 200 OK)

Pagination workflow

HTTP status codes

Did not find what you were looking for?

Did not find what you were looking for?