Querying the API

Filters, date ranges, cursor pagination, and sorting can be combined in the same request and work together seamlessly. Refer to the API Reference for the complete list of valid query parameters and enum values available for each endpoint.

Data hierarchy

The Reporting API is organised around a hierarchy of aggregation: instance → campaign → (platforms, creators, posts). Each endpoint reads at one of those levels (or provides a time-series view at instance level).

Instance
  └── Campaign 
        ├── Platforms - metrics by social platform (e.g. instagram, tiktok)
        ├── Creators - metrics per creator
        └── Posts - metrics per content item(post)

Which endpoint should I use?

Response envelope

Successful reads return a data payload which can be an object or array depending on endpoint, plus a nextCursor field (string or null):

{
  "data": {},
  "nextCursor": null
}

For list endpoints, when more rows exist, nextCursor is an opaque string to pass on the next request (with the same filters, sort, and limit). When there are no further pages, nextCursor is null. The API does not return a total item or page count.

GET /instances/performance returns a single aggregate object in data; nextCursor is always null for that route.

Date range

• startDate / endDate - required on performance routes; use YYYY-MM-DD in UTC.
• Maximum range - two years from startDate; exceeding it returns 400 with a validation error.
• dateBasis - optional; controls which dates filter the data:
  • post_date (default) - content published in the range.
  • performance_date - activity recorded in the range.

performance_date vs post_date

A post published in March can still accumulate performance_date metrics in April (ongoing engagement). For “how much happened in April?” use dateBasis=performance_date. For “what did we publish in April?” use dateBasis=post_date.

Instances and campaigns

• instanceIds - optional string array; scope to specific instances. When omitted, the request is evaluated against every instance associated with your OAuth client; supply one or more values to narrow the response to a subset.
• campaignIds - optional numeric array; at most 50 IDs per request.

platform and contentType

Two mutually exclusive filters let you narrow results by where content was published. You can use one or the other in a request, but not both.

platform — filters by top-level platform. Accepted values: instagram, tiktok, facebook, youtube, twitter, linkedin, pinterest, snapchat, blog, twitch.

contentType — filters by specific content format. Accepted values: instagram_post, instagram_reel, instagram_story, facebook_post, facebook_live, facebook_group, facebook_reel, tiktok, youtube_video, youtube_shorts, twitter, linkedin, pinterest, snapchat_story, blog, twitch_stream.

Use platform when you want all content from a platform (e.g. all Instagram formats). Use contentType when you need a specific format (e.g. only Reels).

Metrics

The metrics parameter is required on the following endpoints (at least one value must be provided):

• GET /instances/performance
• GET /instances/performance-over-time
• GET /campaigns/performance
• GET /platforms/performance
• GET /creators/performance
• GET /posts/performance

Each endpoint accepts a different subset of metrics. See the API Reference for the full list of accepted values per endpoint.

Metric naming conventions

Metric names follow a small set of prefix rules so you can tell at a glance where a number comes from:

• Organic metrics use their base name (e.g. engagements, impressions, cpm).
• Paid metrics are prefixed with paid (e.g. paidEngagements, paidImpressions, paidCpm).
• Tracking link metrics are prefixed with trackingLinks (e.g. trackingLinksClicks, trackingLinksConversions).
• Affiliate link metrics are prefixed with affiliateLinks (e.g. affiliateLinksClicks, affiliateLinksSales, affiliateLinksRoi).

All metric fields are nullable — a null value indicates the metric is not available for the given data (e.g. the platform does not report it, or no activity was recorded in the requested range).

Metrics and platform/contentType filters

When you combine metrics with a platform or contentType filter, the set of valid metrics narrows to only those supported by the selected platforms or content types. If you request a metric that is not available for the current filter, the API returns a 400 error with the list of valid metrics for that filter combination.

Most metrics (e.g. likes, comments, engagements, impressions, reach) work across all platforms. The following metrics are restricted to specific content types:

For example, requesting crosspostedFacebookOnlyViews with platform=tiktok returns an error because that metric is only available for Instagram Reels. The error response includes the full list of valid metrics for your current filters.

Sorting

List endpoints that support ranking expose sortProperty and sortDirection (ASC / DESC). Allowed sortProperty values differ by route - use the API Reference for the authoritative list per operation.

Pagination

Endpoints that support pagination use a cursor-based approach

There is no total count of items (totalItems, totalPages, etc.). Keep requesting with the returned nextCursor until nextCursor is null, which means you have read the full result set for that query.

Changing the walk: Cursors are tied to the exact query that produced them. To change filters, sort, or limit, start again without nextCursor.

GET /instances/performance returns a single aggregated summary; it does not paginate and does not accept limit or nextCursor as query parameters (see the API Reference for that operation).

Time series

GET /instances/performance-over-time accepts granularity: day, week, month, quarter, year (default month). Each point includes bucket startDate and endDate.

Partial-period buckets

Monthly (granularity=month) and weekly buckets include an endDate. If endDate is on or after today (UTC), the bucket is still in progress. Label those buckets “in progress” in charts so readers do not treat them as finalized totals.

Data freshness & consistency

Most endpoints return analytics that are current up to the previous day, as several source media platforms apply a several-hour reporting delay.

Analytics are eventually consistent. Due to the distributed nature of data collection and processing across multiple platforms, updates may take additional time to fully propagate. In rare cases, metrics for a given day may be revised or appear with a short delay even after initially becoming visible.

Analytics are recorded on a daily basis and appear only when they fall within the selected date-range filters.

Related pages

• Errors & troubleshooting
• API Reference