Skip to content
Pomelo Analytics

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

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-Request-Id
string

Optional idempotency/request correlation identifier.

Query Parameters

Section titled “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

Section titled “ Responses ”

200

Section titled “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

Section titled “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

Section titled “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

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

402

Section titled “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

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

403

Section titled “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

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

422

Section titled “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

Section titled “Headers ”
X-Request-Id
string

Request identifier for troubleshooting.

429

Section titled “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

Section titled “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.