Create an Apple Search Ads API key in the Apple Search Ads web UI under Account Settings, download the private key PEM file, and generate a client_secret JWT signed with the key using the ES256 algorithm
Exchange the client_secret for an access token via a POST to the Apple Search Ads auth token endpoint (https://appleid.apple.com/auth/oauth2/token) with grant_type=client_credentials
POST to the reporting endpoint at https://api.searchads.apple.com/api/v5/reports/campaigns with a ReportingRequest body specifying startTime, endTime, granularity (DAILY, WEEKLY, or MONTHLY), and the desired metrics (impressions, taps, conversions, spend, avgCPA)
Parse the reportingDataResponse.row array from the response; each row contains metadata (campaign name, ID) and metrics for the requested granularity
Paginate using the offset and limit fields in the reportingRequest body if the campaign count exceeds the default page size
Note that this API version (v5) is slated for sunset in January 2027; begin planning migration to the new Apple Ads Platform API when it becomes generally available
Known gotchas
JWT client_secret tokens expire after 180 days and must be regenerated; expired tokens cause authentication failures that can silently halt automated reporting pipelines
The Apple Search Ads API enforces rate limits per ACL (access control level); exceeding limits returns HTTP 429 and the retry-after period can be several minutes, requiring back-off logic
Conversion data in Search Ads reports relies on Apple's SKAdNetwork or LAT attribution; for iOS 14.5+ users, conversion counts may be modeled and delayed by up to 24-48 hours due to privacy aggregation
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp