Instance performance over time

Returns time-series performance metrics for the given instances, broken into time buckets.

What is included per time bucket:

Organic metrics (likes, comments, shares, engagements, impressions)
Paid metrics (paid likes, comments, shares, engagements, impressions)
Each data point includes startDate (inclusive) and endDate (inclusive) indicating the bucket boundaries

Use the granularity parameter to control the bucket size (see parameter description for details).

Pagination

Results are paginated. Use pageSize (default: 50, max: 100) and pageNumber (1-indexed) to navigate pages. The response includes a pagination object with page, pageSize, totalPages, and totalItems.

Query Parameters

startDate
Type: stringFormat: date-time
required

Start of the reporting period (inclusive). Format: YYYY-MM-DD.
endDate
Type: stringFormat: date-time
required

End of the reporting period (inclusive). Format: YYYY-MM-DD.
instanceIds
Type: array string[]

One or more instance IDs to limit the query scope. If not provided, the query includes all instances accessible with the API credentials.

Supported array formats: param=a,b,c (comma-separated), param=a&param=b (repeated key), or param[]=a&param[]=b (bracket syntax).
campaignIds
Type: array number[] …50

Filter results to specific campaigns. When omitted, all campaigns are included.

Supported array formats: param=a,b,c (comma-separated), param=a&param=b (repeated key), or param[]=a&param[]=b (bracket syntax).
platform
Type: array string[]enum

Filter by top-level platform. Selecting a platform includes all its content types (e.g. instagram includes instagram_post, instagram_reel, instagram_story).

Cannot be combined with contentType — provide only one of the two.

When omitted (and contentType is also omitted), all platforms are included.

Supported array formats: param=a,b,c (comma-separated), param=a&param=b (repeated key), or param[]=a&param[]=b (bracket syntax).
values
- instagram
- tiktok
- facebook
- youtube
- twitter
contentType
Type: array string[]enum
Filter by specific content type for granular filtering beyond top-level platforms.

instagram_post, instagram_reel, instagram_story — specific Instagram content formats

facebook_post, facebook_live, facebook_group, facebook_reel — specific Facebook content formats

tiktok, youtube_video, youtube_shorts — platform-specific types

Cannot be combined with platform — provide only one of the two.

When omitted (and platform is also omitted), all content types are included.

Supported array formats: param=a,b,c (comma-separated), param=a&param=b (repeated key), or param[]=a&param[]=b (bracket syntax).
values
- instagram_post
- instagram_reel
- instagram_story
- facebook_post
- facebook_live
dateBasis
Type: stringenum
Controls which date dimension is used for filtering.

post_date (default): filters by the date the content was originally published. Best for analyzing content output and creator activity over time.

performance_date: returns metrics recorded within the requested date range, regardless of when the content was originally published. Best for understanding how campaigns performed during a specific reporting window.

Example: a post published on Jan 5 that receives engagement on Feb 10 will appear in a Feb 1–28 query with performance_date, but in a Jan 1–31 query with post_date.
values
- post_date
- performance_date
pageSize
Type: number
min:
1
max:
100

Number of items per page.
pageNumber
Type: number
min:
1
max:
500

Page number (1-indexed).

granularity

Type: stringenum

Controls the time bucket size for the timeseries data.

Value	Behavior
`day`	One bucket per calendar day
`week`	Aggregates by ISO 8601 week (Monday–Sunday)
`month`	Aggregates by calendar month (1st–last day)
`quarter`	Aggregates by calendar quarter (Q1 = Jan–Mar, Q2 = Apr–Jun, Q3 = Jul–Sep, Q4 = Oct–Dec)
`year`	Aggregates by calendar year (Jan 1–Dec 31)

Each data point includes startDate (inclusive) and endDate (inclusive) indicating the bucket boundaries. Partial buckets are returned at the edges of the requested date range.

values

year
quarter
month
week
day

Responses

application/json
application/json
application/json

get/v2/instances/performance-over-time

curl 'https://reporting.api.later.com/v2/instances/performance-over-time?startDate=2024-01-01&endDate=2024-12-31&instanceIds=instance_abc&instanceIds=instance_def&campaignIds=49761&campaignIds=49802&platform=instagram&platform=tiktok&contentType=instagram_reel&contentType=tiktok&dateBasis=post_date&pageSize=50&pageNumber=1&granularity=month' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "endDate": "2024-01-31",
      "metrics": {
        "clicks": 560,
        "comments": 340,
        "cpe": 0.29,
        "cpm": 35.14,
        "engagementRate": 12.32,
        "engagements": 2280,
        "estimatedValueGenerated": 8200,
        "impressions": 18500,
        "likes": 1200,
        "paidComments": 85,
        "paidEngagementRate": 7.88,
        "paidEngagements": 945,
        "paidImpressions": 12000,
        "paidLikes": 400,
        "paidShares": 60,
        "shares": 180
      },
      "startDate": "2024-01-01"
    },
    {
      "endDate": "2024-02-29",
      "metrics": {
        "clicks": 620,
        "comments": 390,
        "cpe": 0.27,
        "cpm": 33.81,
        "engagementRate": 12.71,
        "engagements": 2670,
        "estimatedValueGenerated": 9400,
        "impressions": 21000,
        "likes": 1450,
        "paidComments": 110,
        "paidEngagementRate": 7.78,
        "paidEngagements": 1105,
        "paidImpressions": 14200,
        "paidLikes": 520,
        "paidShares": 75,
        "shares": 210
      },
      "startDate": "2024-02-01"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 2,
    "totalPages": 1
  }
}

Timeseries performance data