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, completed, limited, unavailable or failed. Always inspect state, even after HTTP success. A refresh answers running: charged is true when it started a new walk, and false when the app's walk was already running and the request joined it. limited and unavailable are never charged, and a walk that ends failed is refunded and can be retried. retryAt says when a new request can succeed. Read the status for the outcome; its latest.state 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.
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.
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. This endpoint has its own quiet daily limit, separate from your plan's tracked-app number: 1 on Peek and 3 on Panda, in a rolling 24 hours, shared by a workspace. A refresh always walks the advertiser again; while an app's walk is still running, a refresh by anyone joins that walk and is not counted. A failed refresh is not counted at all.

AI agent or LLM? Read this page as markdown