# TrendTrack Public API agent guide

Primary Markdown entrypoint for agents using the TrendTrack Public API. This page is intentionally concise; follow the section links for endpoint-specific Markdown references.

## Call basics

- Current API base URL: `https://api.trendtrack.io`
- API keys are managed at: https://app.trendtrack.io/workspace/settings/api
- Send `Authorization: Bearer <your-api-key>` on every request.
- JSON request bodies require `Content-Type: application/json`.
- Respect `x-ratelimit-*`, `retry-after`, and credit headers on responses.

## Non-negotiable routing rule

If the user provides a brand name, shop domain, website URL/domain, Instagram handle, Facebook page id, or similar page identifier, call `GET /v1/lookup?q=...&type=auto` first.

Do this before paging `/v1/brandtrackers`, querying shops, choosing advertiser endpoints, or searching ads. Lookup is the zero-credit resolution step that returns linked `brandtracker`, `advertiser`, and `shop` candidates with the public ids needed by later endpoints.

```bash
curl -s "https://api.trendtrack.io/v1/lookup?q=allbirds.com&type=auto" \
  -H "Authorization: Bearer $TRENDTRACK_API_KEY"
```

## Section-specific Markdown

| Topic | Markdown URL | Use it for |
|---|---|---|
| Lookup and resource resolution | [lookup.md](https://docs.trendtrack.io/docs/public-api/lookup.md) | Resolve user-provided brand, domain, social, or page identifiers before choosing resource endpoints. |
| Shops | [shops.md](https://docs.trendtrack.io/docs/public-api/shops.md) | Public shop discovery, advanced shop filters, similar shops, products, and linked advertisers. |
| Brandtrackers | [brandtrackers.md](https://docs.trendtrack.io/docs/public-api/brandtrackers.md) | Workspace-tracked brands, filters, sort enums, overview analytics, rankings, and brandtracker drilldowns. |
| Facets | [facets.md](https://docs.trendtrack.io/docs/public-api/facets.md) | Lookup valid category, technology, pixel, and Shopify app IDs before filtering shops, ads, emails, or advertisers. |
| Ads | [ads.md](https://docs.trendtrack.io/docs/public-api/ads.md) | Public ad search, advanced ad queries, ad detail, and reach history. |
| Advertisers | [advertisers.md](https://docs.trendtrack.io/docs/public-api/advertisers.md) | Advertiser/page discovery, advanced advertiser query filters, ad counts, reach, and growth metrics. |
| Emails | [emails.md](https://docs.trendtrack.io/docs/public-api/emails.md) | Email discovery, advanced email queries, campaigns, languages, and shop email activity. |
| Workspace | [workspace.md](https://docs.trendtrack.io/docs/public-api/workspace.md) | Workspace identity and workspace-wide top ads, hooks, ad copies, landing pages, scaling ads, and media mix. |
| Usage and credits | [usage-and-credits.md](https://docs.trendtrack.io/docs/public-api/usage-and-credits.md) | Credit headers, balance checks, metering behavior, and safe bootstrap calls. |
| Time windows | [time-windows.md](https://docs.trendtrack.io/docs/public-api/time-windows.md) | Snapshot dates, periods, readiness, rankings, and historical analytics semantics. |

## Endpoint selection tree

1. Validate context with `GET /v1/me`; check remaining credits with `GET /v1/usage` when budget matters.
2. Resolve user-provided identifiers with `GET /v1/lookup?q=...`.
3. If lookup returns a tracked brand, use `brandtracker.id` with `/v1/brandtrackers/{brandtrackerId}/overview` first, then drill into top ads or analytics.
4. If lookup returns a shop, use `shop.id` or `shop.domain` with `/v1/shops/{shopId}`, `/v1/shops/{identifier}/similar`, products, emails, or linked advertisers.
5. If the user asks for shops/ads/emails/advertisers in category X, using technology Y, or running pixel/app Z, call `/v1/facets/{categories|technologies|pixels|shopify-apps}` first to get accepted IDs/slugs.
6. If the task is public market discovery rather than a known identifier, use `POST /v1/ads/query`, `POST /v1/shops/query`, `POST /v1/advertisers/query`, or `POST /v1/emails/query` with explicit filters.
7. For workspace-wide questions, use `/v1/workspace/*` endpoints rather than looping through every brandtracker unless the user specifically needs per-brand detail.

## High-signal enum and alias cheatsheet

- Lookup `type`: `auto`, `brandtracker`, `advertiser`, `shop`.
- Brandtracker list filters: `name`, `folderIds`, `folderNames`, `hasNewAdsSince`, `sortBy`.
- Brandtracker list `sortBy`: `newAdsLastDay`, `newAdsLast7Days`, `newAdsLast30Days`, `activeAds`, `totalTraffic`, `name`, `createdAt`.
- Top ads `sortBy`: `currentRank`, `rankDelta`, `rankDelta7d`, `rankDelta14d`, `rankDelta30d`, `reach`, `impressions`, `reachDelta1d`, `reachDelta7d`, `reachDelta30d`, `daysRunning`, `duplicates`.
- Top ads aliases: `impressions` is accepted as a reach alias; rank movers should use `rankDelta7d`, `rankDelta14d`, or `rankDelta30d`.
- Advanced query endpoints use canonical `sortBy` + `order`.
- `GET /v1/ads` canonical param is `search`; deprecated alias `query` is accepted only for backward compatibility. Do not send both.
- Shops query `searchType`: `domain` exact domain/related-domain, `productName`, `shopContains` broad website text. Send `search`, not unsupported `name`, `domain`, or `domains` body keys.
- Category filters: ads/shops use `categoryIds`; advertisers use `categoryIds` for simple filters or `pageNiches` for advanced `main`/`among`/`exclude` logic.

## Cookbook patterns

- Scaling brands: for tracked brands, use workspace or brandtracker `/top-ads` with `sortBy=rankDelta7d|rankDelta14d|rankDelta30d`; for public discovery, query advertisers by supported `sortBy=reach14d` or `activeAds` with `minActiveAds` (advertiser `reachDelta7d` sorting is not supported).
- Brand winners: lookup first, read overview, then compare `currentRank`, `reach`, `rankDelta7d`, and `reachDelta7d` views instead of relying on one score.
- Workspace top-ads row mapping example: `{ "brandtracker": {"id": "...", "name": "..."}, "ad": {"id": "..."}, "metrics": {"rank": 12, "reach": 340000} }`.
- Advertiser categories: resolve category IDs with facets, then send `categoryIds: [id]` to `/v1/advertisers/query`; use `pageNiches` only for advanced `main`/`among`/`exclude` logic.
- Exact shop domain: `POST /v1/shops/query` with `searchType=domain` and `search` set to a domain/URL; use `shopContains` for broad website text discovery.
- Email patterns: lookup known brands/domains first, then query emails by domain/content. Do not promise live inbox coverage, webhooks, or a universal “best email” conversion score.

## Traps to avoid

- Do not paginate `/v1/brandtrackers` as the first step when the user already gave a brand/domain/handle/page id; use `/v1/lookup` first.
- Do not send `name`, `domain`, or `domains` in `POST /v1/shops/query`; use `search` and `searchType`.
- Do not search by category name in `/v1/shops/query`; first call `/v1/facets/categories?search=...` and then use the returned ID in filters.
- Do not add deprecated `period`/`snapshotDate` parameters to canonical current top-ads ranking calls to ask for historical rankings.
- Do not ignore credit and rate-limit headers in loops.

## Core resolution endpoints

- `GET /v1/lookup` — Resolve a brand, advertiser, or shop. Reference: https://docs.trendtrack.io/docs/reference/api/lookup
  - Required: `q` (query).
  - Query enums: `type`=auto|brandtracker|advertiser|shop.
- `GET /v1/me` — Resolve the current API credential. Reference: https://docs.trendtrack.io/docs/reference/api/get-me
- `GET /v1/usage` — Read the current workspace usage snapshot. Reference: https://docs.trendtrack.io/docs/reference/api/get-usage

## Cost

1 credit per row returned. Use the smallest `limit` that answers the question.
Watch `x-credits-remaining` after every metered call. `/v1/me`, `/v1/usage`, and `/v1/lookup` are zero-credit.

## Real-time monitoring

The API does not expose webhooks. For threshold alerts such as "ping me when ad reach > 500k", poll daily on `/v1/brandtrackers/{brandtrackerId}/top-ads` or filter on `createdAfter` and compare client-side.

## Human docs and generated reference

- Docs portal: https://docs.trendtrack.io/docs
- API reference: https://docs.trendtrack.io/docs/reference/api-reference
- Full Markdown dump, if needed: https://docs.trendtrack.io/docs/llms-full.txt