Simple action report with advanced families gated by profile

GET

/v1/reports/actions

Mixed route family. The strict-safe slice covers bounded simple actions (ui.click, outbound.click, file.download, form.submit). Richer families such as goals, errors, and custom events remain profile-gated and are marked through availability.sections as actions_advanced. Use availability.readModel to distinguish the stable baseline from the enriched families unlocked by Extended.

Authorizations

• bearerAuth

Parameters

Header Parameters

X-Request-Id

string

Optional idempotency/request correlation identifier.

Query Parameters

site_id

required

string

tenant_id

string

Stable tenant identifier. Use this for tenant-scoped analytics and tenant-scoped access control. site_id identifies the shared product, tenant_id identifies one tenant.

from

string format: date

Inclusive UTC start date (YYYY-MM-DD). Defaults to last 7 days.

to

string format: date

Inclusive UTC end date (YYYY-MM-DD). Defaults to today.

compare

string

Allowed values: prev_period

Compare current range against the previous equivalent period.

traffic

string

default: humans

Allowed values: humans humans_including_ai bots_only ai_bots_only all

Traffic segment to include.

limit

integer

default: 200 >= 1 <= 2000

Number of rows returned by top lists for report endpoints.

action_family

string

Allowed values: goals forms outbound downloads errors custom instrumentation

Filter action reports by normalized action family.

action_key

string

Filter action reports by normalized action key.

Responses

200

OK. Mixed route: the strict-safe bounded action slice succeeded. availability.readModel shows what belongs to the strict-safe baseline, while availability.sections reports whether actions_advanced remains locked or only partially compatible for the requested period.

object

current

required

object

goals_configured

required

boolean

active_family

required

string

nullable

Allowed values: goals forms outbound downloads errors custom instrumentation

totals

required

object

total_sessions

required

number

meaningful_action_sessions

required

number

meaningful_occurrences

required

number

error_sessions

required

number

instrumentation_sessions

required

number

families

required

Family summary for the current action envelope. On Strict sites, simple bounded families remain available; richer families are exposed through availability.sections as actions_advanced.

Array<object>

object

family

required

string

Allowed values: goals forms outbound downloads errors custom instrumentation

sessions

required

number

occurrences

required

number

timeseries

required

Array<object>

object

date

required

string format: date

total_sessions

required

number

meaningful_action_sessions

required

number

meaningful_occurrences

required

number

error_sessions

required

number

instrumentation_sessions

required

number

family_timeseries

required

Array<object>

object

date

required

string format: date

family

required

string

Allowed values: goals forms outbound downloads errors custom instrumentation

sessions

required

number

occurrences

required

number

actions

required

Exact action rows for the active envelope. On Strict sites, this list is limited to bounded simple actions and stays readable in HTTP 200; advanced families remain section-gated.

Array<object>

object

action_key

required

string

action_name

required

string

event_name

string

nullable

family

required

string

Allowed values: goals forms outbound downloads errors custom instrumentation

action_id

Stable element/action identifier when the action row can be narrowed by it.

string

nullable

action_target_host

Target host when the action row can be narrowed by outbound or download target.

string

nullable

form_id

Form identifier when the form action row can be narrowed by it.

string

nullable

form_action_path

Form action path when the form action row can be narrowed by it.

string

nullable

sessions

required

number

occurrences

required

number

top_page

string

nullable

top_source

string

nullable

Allowed values: Direct Search Referral Social Email Paid Other

context

required

Shared breakdown context for the active action envelope. Advanced action families can remain unavailable even when the route itself succeeds; inspect availability.sections.

object

pages

required

Array<object>

object

scope

required

string

Allowed values: family action

path_canon

string

nullable

sessions

required

number

sources

required

Array<object>

object

scope

required

string

Allowed values: family action

channel

required

string

Allowed values: Direct Search Referral Social Email Paid Other

sessions

required

number

segments

required

Array<object>

object

scope

required

string

Allowed values: family action

kind

required

string

Allowed values: device country browser

label

required

string

sessions

required

number

compare

required

object

goals_configured

required

boolean

active_family

required

string

nullable

Allowed values: goals forms outbound downloads errors custom instrumentation

totals

required

object

total_sessions

required

number

meaningful_action_sessions

required

number

meaningful_occurrences

required

number

error_sessions

required

number

instrumentation_sessions

required

number

families

required

Family summary for the current action envelope. On Strict sites, simple bounded families remain available; richer families are exposed through availability.sections as actions_advanced.

Array<object>

object

family

required

string

Allowed values: goals forms outbound downloads errors custom instrumentation

sessions

required

number

occurrences

required

number

timeseries

required

Array<object>

object

date

required

string format: date

total_sessions

required

number

meaningful_action_sessions

required

number

meaningful_occurrences

required

number

error_sessions

required

number

instrumentation_sessions

required

number

family_timeseries

required

Array<object>

object

date

required

string format: date

family

required

string

Allowed values: goals forms outbound downloads errors custom instrumentation

sessions

required

number

occurrences

required

number

actions

required

Exact action rows for the active envelope. On Strict sites, this list is limited to bounded simple actions and stays readable in HTTP 200; advanced families remain section-gated.

Array<object>

object

action_key

required

string

action_name

required

string

event_name

string

nullable

family

required

string

Allowed values: goals forms outbound downloads errors custom instrumentation

action_id

Stable element/action identifier when the action row can be narrowed by it.

string

nullable

action_target_host

Target host when the action row can be narrowed by outbound or download target.

string

nullable

form_id

Form identifier when the form action row can be narrowed by it.

string

nullable

form_action_path

Form action path when the form action row can be narrowed by it.

string

nullable

sessions

required

number

occurrences

required

number

top_page

string

nullable

top_source

string

nullable

Allowed values: Direct Search Referral Social Email Paid Other

context

required

Shared breakdown context for the active action envelope. Advanced action families can remain unavailable even when the route itself succeeds; inspect availability.sections.

object

pages

required

Array<object>

object

scope

required

string

Allowed values: family action

path_canon

string

nullable

sessions

required

number

sources

required

Array<object>

object

scope

required

string

Allowed values: family action

channel

required

string

Allowed values: Direct Search Referral Social Email Paid Other

sessions

required

number

segments

required

Array<object>

object

scope

required

string

Allowed values: family action

kind

required

string

Allowed values: device country browser

label

required

string

sessions

required

number

range

required

object

start

required

string format: date-time

end

required

string format: date-time

compare_start

required

string format: date-time

nullable

compare_end

required

string format: date-time

nullable

availability

required

Availability contract for profile-aware reads.

For mixed routes, HTTP 200 means the strict-safe base slice was returned successfully. readModel tells you which slices belong to the strict-safe baseline and which belong to Extended. Section-level locks or partial compatibility for enriched sub-slices are reported in sections.

object

route

required

Backend route-family identifier echoed in availability.route. Public /v1/reports/* responses currently use overview, content, acquisition, actions, and goals. audience_* values are reserved for dashboard/internal query families and do not imply standalone /v1/reports/audience* public endpoints.

string

Allowed values: overview content acquisition acquisition_summary acquisition_details audience_summary audience_dimensions audience_profiles technology performance actions goals robots timeseries timeseries_tenant breakdown breakdown_tenant

classification

required

string

Allowed values: strict_safe extended_only mixed

currentProfile

required

string

Allowed values: strict extended

collectionProfileEffectiveAt

required

string format: date-time

nullable

current

required

Route-level availability for the current range. On mixed routes, status=available means the strict-safe base slice is readable; inspect sections for enriched sub-slices that remain locked or partial.

object

status

required

string

Allowed values: available locked_by_profile partially_available_after_effective_at not_available_for_requested_period

reason

required

string

nullable

Allowed values: strict_safe_route extended_data_required requested_period_has_no_extended_data requested_period_crosses_profile_change section_not_collected_in_runtime

requestedStart

required

string format: date-time

requestedEnd

required

string format: date-time

compatibleStart

required

string format: date-time

nullable

compatibleEnd

required

string format: date-time

nullable

compare

required

object

status

required

string

Allowed values: available locked_by_profile partially_available_after_effective_at not_available_for_requested_period

reason

required

string

nullable

Allowed values: strict_safe_route extended_data_required requested_period_has_no_extended_data requested_period_crosses_profile_change section_not_collected_in_runtime

requestedStart

required

string format: date-time

requestedEnd

required

string format: date-time

compatibleStart

required

string format: date-time

nullable

compatibleEnd

required

string format: date-time

nullable

sections

required

Section-level availability for mixed routes. Each entry describes an enriched sub-slice that may remain locked or partially compatible while the enclosing route still returns HTTP 200.

Array<object>

Section-level availability for mixed routes. A mixed route can return HTTP 200 while one or more enriched sections remain locked or only partially compatible for the requested period.

object

id

required

Section identifier for mixed-route sub-slices.

Current meanings:

• overview_regions: region list inside the overview audience slice
• overview_cities: city list inside the overview audience slice
• acquisition_attribution: source/medium/campaign slices on acquisition routes
• actions_advanced: advanced action families outside bounded simple actions
• audience_top_campaigns: optional top_campaigns list on the internal audience_summary family
• technology_regions, technology_cities: geo detail slices on technology routes

overview_acquisition is kept as a legacy compatibility identifier but is not emitted by the current lot2 overview contract because acquisition-lite now lives in the route-level mixed envelope itself.

string

Allowed values: overview_acquisition overview_regions overview_cities acquisition_attribution actions_advanced audience_top_campaigns technology_regions technology_cities

classification

required

string

Allowed values: strict_safe extended_only mixed

current

required

object

status

required

string

Allowed values: available locked_by_profile partially_available_after_effective_at not_available_for_requested_period

reason

required

string

nullable

Allowed values: strict_safe_route extended_data_required requested_period_has_no_extended_data requested_period_crosses_profile_change section_not_collected_in_runtime

requestedStart

required

string format: date-time

requestedEnd

required

string format: date-time

compatibleStart

required

string format: date-time

nullable

compatibleEnd

required

string format: date-time

nullable

compare

required

object

status

required

string

Allowed values: available locked_by_profile partially_available_after_effective_at not_available_for_requested_period

reason

required

string

nullable

Allowed values: strict_safe_route extended_data_required requested_period_has_no_extended_data requested_period_crosses_profile_change section_not_collected_in_runtime

requestedStart

required

string format: date-time

requestedEnd

required

string format: date-time

compatibleStart

required

string format: date-time

nullable

compatibleEnd

required

string format: date-time

nullable

readModel

object

strictSafe

required

Array<string>

Allowed values: overview_core overview_geography acquisition_lite acquisition_attribution actions_simple actions_advanced audience_core audience_campaigns technology_core technology_geography

extended

required

Array<string>

Allowed values: overview_core overview_geography acquisition_lite acquisition_attribution actions_simple actions_advanced audience_core audience_campaigns technology_core technology_geography

Example

{
  "route": "acquisition",
  "classification": "mixed",
  "currentProfile": "strict",
  "collectionProfileEffectiveAt": null,
  "current": {
    "status": "available",
    "reason": null,
    "requestedStart": "2026-04-01T00:00:00.000Z",
    "requestedEnd": "2026-04-30T23:59:59.999Z",
    "compatibleStart": "2026-04-01T00:00:00.000Z",
    "compatibleEnd": "2026-04-30T23:59:59.999Z"
  },
  "compare": null,
  "readModel": {
    "strictSafe": [
      "acquisition_lite"
    ],
    "extended": [
      "acquisition_attribution"
    ]
  },
  "sections": [
    {
      "id": "acquisition_attribution",
      "classification": "extended_only",
      "current": {
        "status": "locked_by_profile",
        "reason": "extended_data_required",
        "requestedStart": "2026-04-01T00:00:00.000Z",
        "requestedEnd": "2026-04-30T23:59:59.999Z",
        "compatibleStart": null,
        "compatibleEnd": null
      },
      "compare": null
    }
  ]
}

meta

required

object

request_id

required

string

units_charged

required

integer

billable_overage

required

boolean

usage

required

object

used_units

required

integer

overage_units

required

integer

included_units

required

integer

hard_cap_units

required

integer

surface

Additive launch-readiness metadata for reports and metrics.

object

mode

required

string

Allowed values: strict extended

dataEnvelope

required

string

Allowed values: strict extended mixed

dataFreshness

required

Freshness metadata for a report or metrics surface.

object

status

required

string

Allowed values: fresh delayed stale unknown

asOf

string format: date-time

nullable

lagMinutes

integer

nullable

cached

boolean

notes

Array<string>

compareWindow

required

Compare window metadata for report and metrics surfaces.

object

enabled

required

boolean

mode

string

nullable

Allowed values: prev_period

compareStart

string format: date-time

nullable

compareEnd

string format: date-time

nullable

exportCapability

required

Export availability for the returned surface and selected plan.

object

csv

required

boolean

level

required

string

Allowed values: none limited standard guardrailed advanced custom

dataEnvelope

required

string

Allowed values: strict extended mixed

notes

Array<string>

Examples

Strict site with simple actions available and advanced families locked

{
  "current": {
    "active_family": "forms",
    "totals": {
      "total_sessions": 980,
      "meaningful_action_sessions": 121,
      "meaningful_occurrences": 156,
      "error_sessions": 0,
      "instrumentation_sessions": 42
    },
    "families": [
      {
        "family": "forms",
        "sessions": 44,
        "occurrences": 51
      },
      {
        "family": "outbound",
        "sessions": 39,
        "occurrences": 55
      },
      {
        "family": "downloads",
        "sessions": 18,
        "occurrences": 22
      },
      {
        "family": "instrumentation",
        "sessions": 42,
        "occurrences": 28
      }
    ],
    "actions": [
      {
        "action_key": "forms::demo_request",
        "action_name": "demo_request",
        "event_name": "form.submit",
        "family": "forms",
        "form_id": "demo_request",
        "sessions": 44,
        "occurrences": 51,
        "top_page": "/pricing",
        "top_source": "Search"
      }
    ],
    "context": {
      "pages": [
        {
          "scope": "family",
          "path_canon": "/pricing",
          "sessions": 44
        }
      ],
      "sources": [
        {
          "scope": "family",
          "channel": "Search",
          "sessions": 31
        }
      ],
      "segments": [
        {
          "scope": "family",
          "kind": "device",
          "label": "desktop",
          "sessions": 28
        }
      ]
    }
  },
  "compare": null,
  "range": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-04-30T23:59:59.999Z",
    "compare_start": null,
    "compare_end": null
  },
  "availability": {
    "route": "actions",
    "classification": "mixed",
    "currentProfile": "strict",
    "collectionProfileEffectiveAt": null,
    "current": {
      "status": "available",
      "reason": null,
      "requestedStart": "2026-04-01T00:00:00.000Z",
      "requestedEnd": "2026-04-30T23:59:59.999Z",
      "compatibleStart": "2026-04-01T00:00:00.000Z",
      "compatibleEnd": "2026-04-30T23:59:59.999Z"
    },
    "compare": null,
    "readModel": {
      "strictSafe": [
        "actions_simple"
      ],
      "extended": [
        "actions_advanced"
      ]
    },
    "sections": [
      {
        "id": "actions_advanced",
        "classification": "extended_only",
        "current": {
          "status": "locked_by_profile",
          "reason": "extended_data_required",
          "requestedStart": "2026-04-01T00:00:00.000Z",
          "requestedEnd": "2026-04-30T23:59:59.999Z",
          "compatibleStart": null,
          "compatibleEnd": null
        },
        "compare": null
      }
    ]
  },
  "meta": {
    "units_charged": 6,
    "billable_overage": false,
    "usage": {
      "used_units": 32,
      "overage_units": 0,
      "included_units": 100,
      "hard_cap_units": 250
    }
  }
}

Headers

X-Request-Id

string

Request identifier for troubleshooting.

X-RateLimit-Limit

integer

Maximum requests allowed during current short window.

X-RateLimit-Remaining

integer

Remaining requests in current short window.

X-RateLimit-Reset

integer

Unix timestamp when short window resets.

401

Invalid or revoked API token.

object

error

required

object

code

required

string

Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND

message

required

string

request_id

required

string

details

object

key

additional properties

any

Headers

X-Request-Id

string

Request identifier for troubleshooting.

402

Billing hard cap reached for current month.

object

error

required

object

code

required

string

Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND

message

required

string

request_id

required

string

details

object

key

additional properties

any

Headers

X-Request-Id

string

Request identifier for troubleshooting.

403

Token scope/site/plan does not allow this request.

object

error

required

object

code

required

string

Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND

message

required

string

request_id

required

string

details

object

key

additional properties

any

Headers

X-Request-Id

string

Request identifier for troubleshooting.

422

Request parameters are invalid.

object

error

required

object

code

required

string

Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND

message

required

string

request_id

required

string

details

object

key

additional properties

any

Headers

X-Request-Id

string

Request identifier for troubleshooting.

429

Request was throttled.

object

error

required

object

code

required

string

Allowed values: UNAUTHORIZED FORBIDDEN INVALID_METHOD INVALID_PARAMS RETENTION_EXCEEDED RATE_LIMITED HARD_CAP_REACHED REPORT_LOCKED_BY_PROFILE REPORT_NOT_AVAILABLE_FOR_REQUESTED_PERIOD REPORT_RESPONSE_TOO_LARGE INTERNAL_ERROR NOT_FOUND

message

required

string

request_id

required

string

details

object

key

additional properties

any

Headers

X-Request-Id

string

Request identifier for troubleshooting.

X-RateLimit-Limit

integer

Maximum requests allowed during current short window.

X-RateLimit-Remaining

integer

Remaining requests in current short window.

X-RateLimit-Reset

integer

Unix timestamp when short window resets.