ZEzernio
Ad Campaigns

Rank ads by performance

Changed on

Returns an ads account's ads ranked by spend, impressions, clicks, results or ROAS over a date range, each with its creative (type, thumbnail, headline, body, link) and campaign.

Use it to see which creatives perform best. accountId is sibling-expanded like /v1/ads/timeline.

Money is ranked by its raw amount, so pass adAccountId when the connection's ad accounts bill in different currencies.

A Meta range older than the imported history answers 202 with backfillPending: true and the covered part; repeat the request until it returns 200.

get/v1/ads/performance

Request

Query parameters

accountIdstring required

Account ID. Sibling-expanded to its linked posting and ads pair. An id the API key cannot reach answers 404.

adAccountIdstring

Optional platform-native ad account ID (e.g. Meta act_…) to rank one ad account only.

fromDatestring date required

Inclusive start of the range (YYYY-MM-DD).

toDatestring date required

Inclusive end of the range (YYYY-MM-DD). Max 730-day range.

platform'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter' | 'openai' | 'reddit' | 'microsoft'

Restrict to one platform.

sortBy'spend' | 'impressions' | 'clicks' | 'conversions' | 'roas'

Metric the ads are ranked by, highest first.

limitinteger

How many ads to return.

Response

Ads ranked by sortBy. Ads with no delivery in the range are left out.

Changes

  • 0398bdc3135eRevision changes
    • warning

      added the new text enum value to the /// response property for the response status

    • warning

      added the new text enum value to the /////// response property for the response status

  • e95a262fd1f4Revision changes
    • info

      added the non-success response with the status