PeekPanda markpeekpandaDocumentation
For your AI
Copy pageCopy entire docs
Dashboard

Refresh competitor paid ads

Look for an iOS app's newest paid ads now instead of waiting for the next scheduled pass.

Download Markdown ↓

POSThttps://api.peekpanda.com/v1/competitors/{platform}/{storeId}/paid-ads/refresh

Request

No request body. Send an Idempotency-Key when a client may retry.

Parameters

NameInTypeRequiredDescription
platformpathiosYesPaid-ad refresh supports iOS apps.
storeIdpathnumeric stringYesApple App Store identifier.

Response

state is running, fresh, completed, limited, not_matched, unavailable or failed. Always inspect state, even after HTTP success. charged says whether the request counted against your refreshes. An app already refreshed today answers with that refresh (running, not_matched, or fresh once it finished) and is not charged; limited and unavailable are never charged, and a failed refresh is refunded and can be retried. retryAt says when a new request can succeed. not_matched means no advertiser has the exact app name.

Response fields

appStoreIdstring
statestring
chargedboolean
retryAtnull
latest.statestring
latest.requestedAtstring
latest.settledAtnull
latest.newAdCountnull
quota.kindstring
quota.limitnumber
quota.usednumber
quota.remainingnumber
quota.resetAtstring

Authentication

Requires Bearer API credential or OAuth access token. Scope content:write. MCP calls refresh with action ad_refresh.

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.
404not_found when the record is outside the accessible catalogue.
429rate_limited; honor Retry-After when present.
409conflict when the write would duplicate an exclusive row.

MCP request

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

{
  "name": "refresh",
  "arguments": {
    "request": {
      "action": "ad_refresh",
      "params": {
        "platform": "<platform>",
        "storeId": "<storeId>"
      }
    }
  }
}

Source

Public ads from the app's own advertiser page, matched by its exact app name. Ads are attributed only when the advertiser matches; no looser name matching is used.

Refresh

A refresh walks the advertiser from its newest ad. It counts against your plan: Peek 1 and Panda 3 refreshes in a rolling 24 hours, shared by a workspace. An app refreshed today, by anyone, is not counted again; a failed refresh is not counted at all.

AI agent or LLM? Read this page as markdown