Browse paid-ad shelves

Read paid ads as per-advertiser shelves, plus shelves for newly launched and long-running creatives.

Last reviewed October 19, 2026Download Markdown ↓

GEThttps://api.peekpanda.com/v1/paid-ads/rails

Request

Every filter is optional. This read serves stored ads and does not collect new ones.

Parameters

NameInTypeRequiredDescription

categoryquerycategoryNoLimit shelves to one category.

platformquerymeta | tiktokNoAdvertising platform.

searchquerystring, max 120NoAdvertiser or creative text. Shelves are grouped from every match, so a search matching more than 30,000 ads answers 422 invalid_request; use a more specific term, or page the matches through Search paid ads.

sortquerymost_tested | longest_running | most_live | recently_trackedNoOrder of the advertiser shelves. Defaults to most_tested.

railSizequeryinteger, 4-20NoCreatives on each shelf. Defaults to 10.

advertiserLimitqueryinteger, 1-20NoAdvertiser shelves to return. Defaults to 8.

Response

rails is empty when nothing is stored. totals uses the same counts as the ranking read.

Response fields

generatedAtstring

railsarray

totals.adsnumber

totals.liveAdsnumber

totals.advertisersnumber

totals.liveAdvertisersnumber

totals.newAdsLast7Daysnumber

totals.advertisersShippingLast7Daysnumber

totals.stoppedLast7Daysnumber

totals.halfLifeDaysnumber

totals.stillRunningAt30Daysnumber

totals.medianRunDaysnumber

totals.longestRunDaysnumber

totals.liveBeyond60Daysnumber

totals.reachDisclosedAdsnumber

totals.unlinkedAdsnumber

totals.uncategorizedLiveAdsnumber

Authentication

Requires Bearer API credential or OAuth access token. Scope context:read. MCP calls get_ads with action rails.

Errors

400invalid_request for an invalid filter, identity or limit.

401authentication_required for a missing or invalid credential.

402subscription_required when access is not entitled.

403authorization_required for a missing scope or unavailable preview access.

403workspace_not_accessible when x-genviral-tenancy names a workspace the credential cannot reach.

404not_found when the record is outside the accessible catalogue.

429rate_limited; honor Retry-After when present.

429daily_call_limit; the plan's daily API and MCP calls are used until 00:00 UTC.

MCP request

Call get_ads with action rails. Path fields go in params, filters in query, and a write body in body.

{
  "name": "get_ads",
  "arguments": {
    "request": {
      "action": "rails"
    }
  }
}

Source

Stored paid-ad observations. Rankings count creatives and how long they stay live. There is no spend or impression field.

Refresh

These reads do not collect new ads.

AI agent or LLM? Read this page as markdown