Analytics

Understand stored post analytics, live provider analytics, workspace scope, filters, and pagination.

Two analytics surfaces

RelayAPI exposes two complementary analytics surfaces:

Stored analytics are useful for cross-platform reporting and smart scheduling. Native analytics expose provider-specific audience and account dimensions when the connected account has the required provider scopes.

Workspace isolation

Every stored analytics row is authorized through its owning post's workspace_id. A post target or analytics snapshot cannot widen that authority.

• With an all-workspace key, omitting workspace_id returns every post in the organization.
• With a workspace-scoped key, omission returns every post that key may access. This is not an authorization bypass.
• Organization-scoped posts (workspace_id: null) are shared with credentials that have at least one workspace grant. A zero-grant credential sees no operational rows.
• Supplying workspace_id narrows the query and is always checked against the key's grants.
• Supplying account_id or post_id first validates that resource's organization and workspace. An inaccessible resource returns 403; an unknown or foreign-organization resource returns 404.

Native account analytics apply the connected account's workspace boundary in the same way.

Post analytics and pagination

GET /v1/analytics accepts workspace_id, account_id, post_id, platform, from_date, to_date, limit, and offset.

curl --get https://api.relayapi.dev/v1/analytics \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  --data-urlencode "workspace_id=ws_example" \
  --data-urlencode "platform=youtube" \
  --data-urlencode "limit=20"

The response separates the current page from totals across the complete filtered result:

{
  "data": [],
  "overview": {
    "total_posts": 42,
    "total_impressions": 12000,
    "total_likes": 830,
    "total_comments": 91,
    "total_shares": 54,
    "total_clicks": 210,
    "total_views": 9900
  },
  "has_more": true,
  "next_offset": 20,
  "truncated": true
}

Follow next_offset while has_more is true. limit defaults to 20 and accepts 1–100. truncated remains as a compatibility signal that the complete matching target set is larger than the returned page.

Aggregates and timelines

Best-time cache entries include the organization, credential workspace scope, exact workspace filter, account, platform, and date window. Metrics from one authorization boundary therefore cannot satisfy another boundary's cache lookup.

Live platform analytics

Use the native endpoints when you need account-level follower, reach, audience, or provider-specific dimensions:

GET /v1/analytics/channels
GET /v1/analytics/platform/overview?account_id=acc_example
GET /v1/analytics/platform/posts?account_id=acc_example
GET /v1/analytics/platform/audience?account_id=acc_example
GET /v1/analytics/platform/daily?account_id=acc_example

Availability varies by platform, account type, app review, and granted OAuth scopes. A connected account can publish successfully while native analytics remain unavailable; inspect the endpoint response and reconnect the account when it reports missing scopes.

Smart scheduling

The same scoped best-time signal feeds scheduled_at: "auto". Auto-scheduling narrows historical engagement and collision checks to the new post's exact workspace. Calling GET /v1/queue/find-slot directly uses the caller's complete authorized workspace scope.