Querying the API

How filters, date basis, pagination, and sorting work together. Valid query parameters and enums for each route are defined in the API Reference.

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:
- performance_date (default) — activity recorded in the range.
- post_date — content published in the range.

Instances and campaigns

instanceIds — optional string array; scope to specific workspaces. Omit only when your contract allows all accessible instances.
campaignIds — optional numeric array; at most 50 IDs per request.

Array query styles (comma-separated, repeated key, or bracket syntax) are accepted; see parameter descriptions in the API Reference.

`platformTypes`

Filters by content/network dimension. Allowed values are listed on each operation in the API Reference (for example instagram_reel, instagram_story, facebook_reel, facebook_group, tiktok, youtube_shorts, and others).

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

Parameter	Default	Min	Max
`pageSize`	50	1	100
`pageNumber`	1	1	500

Response shape:

{
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalPages": 24,
    "totalItems": 1200
  }
}

Time series

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

`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.

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.

Core Concepts

Rate limiting(TBD)