Référence API
Parcourez la référence groupée par endpoints pour shops, advertisers, ads, favorites, usage et workspace.
Resource-based navigation
Use the left sidebar to browse the API by resource area instead of endpoint-by-endpoint. Each resource page lists every operation in that group with request and response samples.
Jump to a resource
Search Shopify stores, pull analytics, and inspect store-level traffic, product, and Meta ad signals.
Query ad creatives across Meta, TikTok, and Facebook. Filter by status, media type, sort, and pagination.
Look up Meta advertiser pages, their active ads, and aggregate performance signals tracked by Trendtrack.
List workspace brandtrackers, resolve brandtrackerId, start with overview,
then use /top-ads?sortBy=currentRank for current rank or
rankDelta7d|rankDelta14d|rankDelta30d for movers. Scaling/ad-rank are
legacy compatibility endpoints.
Resolve a brand name, domain, Facebook page ID, or Instagram handle via GET /v1/lookup and pivot to linked brandtracker, advertiser, and shop resource
IDs.
Read and manage the favorites (saved items) belonging to the authenticated workspace.
Retrieve metadata about the workspace attached to the API key making the call.
Check remaining credits, billing period, and metered consumption for the current workspace.
Inspect the owner and scopes of the API key presented in the request.
Probe public surface endpoints — health, metadata, shell routes, and
freshness checks like GET /v1/system/freshness before production traffic.
Endpoints for email-specific lookups and exports supported by the API.
Common naming and filtering conventions
- Public API base URL:
https://api.trendtrack.io. - Public query surfaces use canonical sort fields
sortByandorder. GET /v1/adscanonical query param issearch; deprecated aliasqueryis accepted for backward compatibility, but sending bothsearchandqueryin one request returns a conflict validation error.GET /v1/advertiserssupports simplecategoryIdsfilters.POST /v1/advertisers/querysupports eithercategoryIdsshorthand orpageNiches(not both). Empty{}bodies are valid for the POST query endpoint.GET /v1/shopssupportscategoryIds,pixelIds,excludePixelIds,shopifyAppIds, andexcludeShopifyAppIdsfilters.POST /v1/shops/querywithsearchType: "domain"performs exact domain/related-domain matching from a domain or URL (no broad wildcard/text fallback). UsesearchType: "shopContains"for broad website text discovery.GET /v1/lookupreturns additivesignalsfields to help disambiguate close matches before metered calls.- Workspace top-ads rows are nested objects
{ brandtracker, ad, metrics }(not a flat ad row). - Folder discovery is available on both
GET /v1/workspace/foldersandGET /v1/brandtrackers/folders. - Email endpoints do not expose opens/clicks/conversions/revenue metrics. Email sort fields are discovery/indexing sorts, not “best-performing email” KPIs.
- For scaling workflows, advertiser
reachDelta7dsorting is not supported; use supported advertiser sorts (reach14d,activeAds, etc.) or mover sorts on brandtracker/workspace top-ads. reachPeriodchooses the metric window used by reach/spend thresholds. By itself it does not filter unless paired withminReach,maxReach, or an endpoint-specific reach sort/filter.
Recommended workflow
- Start with Getting Started to obtain a key and make a first call.
- Confirm Authentication so every subsequent request carries
Authorization: Bearer <key>. - For brand/domain/Facebook page ID/Instagram handle questions, call
GET /v1/lookup?q=...first (zero-credit), then pivot to the linkedbrandtracker,advertiser, orshopresource IDs. - For tracked-brand deep dives, use
GET /v1/brandtrackers/{brandtrackerId}/overviewfirst. - For rankings, use canonical top-ads calls:
GET /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=currentRankorGET /v1/workspace/top-ads?sortBy=currentRank. - For rank movers, use
sortBy=rankDelta7d,rankDelta14d, orrankDelta30d; usereach,reachDelta1d,reachDelta7d, orreachDelta30dfor reach rankings. - Treat
/scaling-adsand/ad-rankas legacy compatibility endpoints; their ES-backed responses may return an emptytrajectory. - For freshness-sensitive historical workflows, check
GET /v1/system/freshness(global) andGET /v1/brandtrackers/{brandtrackerId}/snapshots(brandtracker-level readiness). - Keep Credits & Billing, Rate Limits, and Errors open while integrating — you will hit them.
- Drill into the resource pages above (or the sidebar) for the exact request shape of each operation.
No in-page playground
The API reference does not ship a hosted playground. Copy the request sample on each operation, swap in your bearer API key, and run it from your own terminal or HTTP client. This keeps the reference fast to scan and avoids surprise network calls while you read.
Return to the docs overview for the guided entry point.