Brandtrackers

List brandtrackers

Returns the workspace-scoped active brandtrackers attached to the authenticated public API workspace. The public identifier is brandtracker.id; legacy spyders.uuid values are accepted when migration metadata exists.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Query Parameters

page?integer

Default1

Range1 <= value

limit?integer

Default20

Range1 <= value <= 100

hasNewAdsSince?string

ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.

Formatdate-time

name?string

Case-insensitive contains match against brandtracker name.

Lengthlength <= 200

sortBy?string

Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.

folderIds?array<>

Folder ids. Repeated query params and comma-separated values are both accepted.

folderNames?array<string>

Folder name search terms. Matches are case-insensitive contains checks. Repeated query params and comma-separated values are both accepted.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
      "name": "Example Brand",
      "facebookPageId": "61554990830184",
      "workspaceLinkId": 99,
      "targetType": "shop",
      "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
      "domain": "examplebrand.com",
      "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
      "status": {
        "isLoaded": true,
        "lastCrawledAt": "2026-04-20T10:00:00.000Z"
      },
      "workspaceAddedAt": "2026-04-15T09:00:00.000Z",
      "folder": {
        "id": 42,
        "name": "Competitors"
      },
      "advertising": {
        "activeAds": 18,
        "newAdsLastDay": 3,
        "newAdsLast7Days": 11,
        "newAdsLast30Days": 34
      },
      "websites": [
        {
          "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
          "domain": "examplebrand.com",
          "siteName": "Example Brand",
          "trafficNumber": 145230,
          "trafficChange": 12.4,
          "monthlyTraffic": {
            "2026-01": 102343,
            "2026-02": 114230
          },
          "socialNetworks": {
            "facebook": "https://facebook.com/examplebrand",
            "instagram": "https://instagram.com/examplebrand",
            "youtube": "https://youtube.com/@examplebrand"
          }
        }
      ],
      "totalTraffic": 145230
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 128,
    "totalPages": 6
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Create a brandtracker

Creates or reactivates a workspace brandtracker by exactly one target identifier: facebookPageId, websiteId, shopId (alias of websiteId), or domain. Domains are normalized and must resolve to exactly one known website. State-changing create/reactivate requests consume one brandtracker create/delete quota unit and one active brandtracker slot; already-active no-ops return 200 and cost 0 units.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

facebookPageId?string

Meta/Facebook page identifier to track. Exactly one of facebookPageId, websiteId, shopId, or domain is required.

websiteId?string

Website/shop identifier to track as a shop-level brandtracker. Exactly one target identifier is accepted.

Formatuuid

shopId?string

Alias of websiteId for shop-oriented clients. Exactly one target identifier is accepted.

Formatuuid

domain?string

Shop domain to resolve to exactly one known website and track as a shop-level brandtracker. Protocols, paths, and a leading www. are normalized away.

folderId?|

Workspace brandtracker folder id. Null or omitted attaches the brandtracker at root.

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/brandtrackers" \  -H "Content-Type: application/json" \  -d '{}'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
    "name": "Example Brand",
    "facebookPageId": "61554990830184",
    "workspaceLinkId": 99,
    "targetType": "shop",
    "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
    "domain": "examplebrand.com",
    "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
    "status": {
      "isLoaded": true,
      "lastCrawledAt": "2026-04-20T10:00:00.000Z"
    },
    "workspaceAddedAt": "2026-04-15T09:00:00.000Z",
    "folder": {
      "id": 42,
      "name": "Competitors"
    },
    "advertising": {
      "activeAds": 18,
      "newAdsLastDay": 3,
      "newAdsLast7Days": 11,
      "newAdsLast30Days": 34
    },
    "websites": [
      {
        "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
        "domain": "examplebrand.com",
        "siteName": "Example Brand",
        "trafficNumber": 145230,
        "trafficChange": 12.4,
        "monthlyTraffic": {
          "2026-01": 102343,
          "2026-02": 114230
        },
        "socialNetworks": {
          "facebook": "https://facebook.com/examplebrand",
          "instagram": "https://instagram.com/examplebrand",
          "youtube": "https://youtube.com/@examplebrand"
        }
      }
    ],
    "totalTraffic": 145230
  },
  "created": true
}

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
    "name": "Example Brand",
    "facebookPageId": "61554990830184",
    "workspaceLinkId": 99,
    "targetType": "shop",
    "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
    "domain": "examplebrand.com",
    "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
    "status": {
      "isLoaded": true,
      "lastCrawledAt": "2026-04-20T10:00:00.000Z"
    },
    "workspaceAddedAt": "2026-04-15T09:00:00.000Z",
    "folder": {
      "id": 42,
      "name": "Competitors"
    },
    "advertising": {
      "activeAds": 18,
      "newAdsLastDay": 3,
      "newAdsLast7Days": 11,
      "newAdsLast30Days": 34
    },
    "websites": [
      {
        "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
        "domain": "examplebrand.com",
        "siteName": "Example Brand",
        "trafficNumber": 145230,
        "trafficChange": 12.4,
        "monthlyTraffic": {
          "2026-01": 102343,
          "2026-02": 114230
        },
        "socialNetworks": {
          "facebook": "https://facebook.com/examplebrand",
          "instagram": "https://instagram.com/examplebrand",
          "youtube": "https://youtube.com/@examplebrand"
        }
      }
    ],
    "totalTraffic": 145230
  },
  "created": true
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtracker folders

Returns the active workspace brandtracker folders so clients can resolve folder ids for brandtracker filters. Equivalent folder listing is also available at GET /v1/workspace/folders.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/folders"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": 12,
      "name": "Competitors",
      "rank": 1,
      "brandtrackerCount": 8
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Create a brandtracker folder

Creates a workspace brandtracker folder and assigns the next rank atomically. Folder mutations are workspace-scoped, metered, and audited.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Workspace-scoped folder name. Rank is assigned atomically as the next workspace rank.

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/brandtrackers/folders" \  -H "Content-Type: application/json" \  -d '{    "name": "Competitors"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": 12,
    "name": "Competitors",
    "rank": 1,
    "brandtrackerCount": 8
  }
}

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": 12,
    "name": "Competitors",
    "rank": 1,
    "brandtrackerCount": 8
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Rename a brandtracker folder

Renames a workspace brandtracker folder. The folder id must belong to the authenticated workspace; cross-workspace ids are returned as not found before any state change.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*integer

Range1 <= value

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

New workspace-scoped folder name.

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/brandtrackers/folders/1" \  -H "Content-Type: application/json" \  -d '{    "name": "Priority Competitors"  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": 12,
    "name": "Competitors",
    "rank": 1,
    "brandtrackerCount": 8
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Delete a brandtracker folder

Deletes a workspace folder. move-to-default moves active brandtrackers to root; delete-brandtrackers deactivates affected workspace links. confirm must be true. The delete-brandtrackers action consumes one persistent brandtracker create/delete quota operation for the whole folder and decrements active brandtracker usage by the affected active-link count; no partial mutation is committed when quota is exhausted.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*integer

Range1 <= value

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

action*string

move-to-default keeps affected trackers active and clears their folder. delete-brandtrackers deactivates affected active workspace links, consumes one persistent create/delete quota unit for the whole folder delete, and decrements active brandtracker usage by affectedCount.

Value in"move-to-default" | "delete-brandtrackers"

confirm*boolean

Must be true for destructive folder delete requests.

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/brandtrackers/folders/1" \  -H "Content-Type: application/json" \  -d '{    "action": "move-to-default",    "confirm": true  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "deleted": true,
    "action": "move-to-default",
    "affectedCount": 12
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Move brandtracker workspace links

Moves active workspace brandtracker links by exactly one address set: brandtrackerIds or workspaceLinkIds. The destination folder id must belong to the authenticated workspace; null moves links to root. Move operations are metered and audited but do not consume persistent create/delete quota or change active brandtracker usage.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

brandtrackerIds?array<string>

Public brandtracker ids to move. Exactly one of brandtrackerIds or workspaceLinkIds is required.

workspaceLinkIds?array<number>

Workspace link ids to move. Exactly one of brandtrackerIds or workspaceLinkIds is required.

folderId*|

Destination workspace folder id, or null to move to root.

Response Body

`application/json`

curl -X PATCH "https://api.trendtrack.io/v1/brandtrackers/workspace-links" \  -H "Content-Type: application/json" \  -d '{    "folderId": 42  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "requestedCount": 3,
    "affectedCount": 2,
    "notFoundBrandtrackerIds": [
      "string"
    ],
    "notFoundWorkspaceLinkIds": [
      0
    ]
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Bulk delete brandtracker workspace links

Deactivates active workspace brandtracker links by exactly one address set: brandtrackerIds or workspaceLinkIds. confirm must be true. Bulk delete consumes one persistent brandtracker create/delete quota operation for the request, reports requested/affected/not-found ids, and decrements active brandtracker usage by the affected active-link count.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

brandtrackerIds?array<string>

Public brandtracker ids to delete. Exactly one of brandtrackerIds or workspaceLinkIds is required.

workspaceLinkIds?array<number>

Workspace link ids to delete. Exactly one of brandtrackerIds or workspaceLinkIds is required.

confirm*boolean

Must be true for destructive bulk delete requests.

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/brandtrackers/workspace-links" \  -H "Content-Type: application/json" \  -d '{    "confirm": true  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "requestedCount": 3,
    "affectedCount": 2,
    "notFoundBrandtrackerIds": [
      "string"
    ],
    "notFoundWorkspaceLinkIds": [
      0
    ]
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get a brandtracker

Returns the detail payload for one active workspace brandtracker resolved from brandtracker.id.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
    "name": "Example Brand",
    "facebookPageId": "61554990830184",
    "workspaceLinkId": 99,
    "targetType": "shop",
    "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
    "domain": "examplebrand.com",
    "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
    "status": {
      "isLoaded": true,
      "lastCrawledAt": "2026-04-20T10:00:00.000Z"
    },
    "workspaceAddedAt": "2026-04-15T09:00:00.000Z",
    "folder": {
      "id": 42,
      "name": "Competitors"
    },
    "advertising": {
      "activeAds": 18,
      "newAdsLastDay": 3,
      "newAdsLast7Days": 11,
      "newAdsLast30Days": 34
    },
    "websites": [
      {
        "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
        "domain": "examplebrand.com",
        "siteName": "Example Brand",
        "trafficNumber": 145230,
        "trafficChange": 12.4,
        "monthlyTraffic": {
          "2026-01": 102343,
          "2026-02": 114230
        },
        "socialNetworks": {
          "facebook": "https://facebook.com/examplebrand",
          "instagram": "https://instagram.com/examplebrand",
          "youtube": "https://youtube.com/@examplebrand"
        }
      }
    ],
    "totalTraffic": 145230,
    "createdAt": "2026-04-01T12:00:00.000Z",
    "updatedAt": "2026-04-21T09:30:00.000Z",
    "pageProfile": {
      "about": "Global fashion brand",
      "category": "Clothing (Brand)",
      "facebookLikes": 523400,
      "instagramFollowers": 841200,
      "instagramUsername": "examplebrand",
      "profileUri": "https://www.facebook.com/examplebrand",
      "runningAds": 18
    },
    "statistics": {
      "urlCount": {
        "https://examplebrand.com/products/hero": 14
      },
      "ctaCount": {
        "SHOP_NOW": 10,
        "LEARN_MORE": 4
      },
      "liveAdCount": {
        "activeCount": 18,
        "inactiveCount": 4
      },
      "formatCount": {
        "IMAGE": 8,
        "VIDEO": 10
      },
      "euData": null
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Delete a brandtracker

Marks the workspace brandtracker inactive while preserving the workspace link and workspace-scoped metadata for reconstructability/reactivation. The shared global brandtracker row is preserved.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Response Body

`application/json`

curl -X DELETE "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
    "deleted": true
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtrackers in a folder

Returns the workspace-scoped active brandtrackers assigned to the requested folder. This is equivalent to /v1/brandtrackers?folderIds=:folderId.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

folderId*integer

Workspace brandtracker folder id.

Range1 <= value

Query Parameters

page?integer

Default1

Range1 <= value

limit?integer

Default20

Range1 <= value <= 100

hasNewAdsSince?string

ISO date/time lower bound. Returns brandtrackers with positive new-ad deltas recorded on or after this timestamp.

Formatdate-time

name?string

Case-insensitive contains match against brandtracker name.

Lengthlength <= 200

sortBy?string

Sort key. Metric and createdAt sorts are descending; name sorts ascending. Omit to preserve default workspace ordering.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/folders/1/brandtrackers"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
      "name": "Example Brand",
      "facebookPageId": "61554990830184",
      "workspaceLinkId": 99,
      "targetType": "shop",
      "websiteId": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
      "domain": "examplebrand.com",
      "avatarUrl": "https://medias.trendtrack.io/profile_picture/61554990830184.jpg",
      "status": {
        "isLoaded": true,
        "lastCrawledAt": "2026-04-20T10:00:00.000Z"
      },
      "workspaceAddedAt": "2026-04-15T09:00:00.000Z",
      "folder": {
        "id": 42,
        "name": "Competitors"
      },
      "advertising": {
        "activeAds": 18,
        "newAdsLastDay": 3,
        "newAdsLast7Days": 11,
        "newAdsLast30Days": 34
      },
      "websites": [
        {
          "id": "3d6fd2f0-5b34-4ffc-91ff-f59775544e5f",
          "domain": "examplebrand.com",
          "siteName": "Example Brand",
          "trafficNumber": 145230,
          "trafficChange": 12.4,
          "monthlyTraffic": {
            "2026-01": 102343,
            "2026-02": 114230
          },
          "socialNetworks": {
            "facebook": "https://facebook.com/examplebrand",
            "instagram": "https://instagram.com/examplebrand",
            "youtube": "https://youtube.com/@examplebrand"
          }
        }
      ],
      "totalTraffic": 145230
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 128,
    "totalPages": 6
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtracker snapshot dates

Returns available ad reach snapshot dates and readiness status for one active workspace brandtracker. latestDate is preserved as a compatibility alias of latestReadyDate; snapshotDate=latest resolves to the latest ready date.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of snapshot dates to return. Defaults to 100.

Default100

Range1 <= value <= 365

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/snapshots"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "latestDate": "2026-04-20",
    "latestReadyDate": "2026-04-20",
    "latestScheduledDate": "2026-04-21",
    "dates": [
      "2026-04-20",
      "2026-04-19"
    ],
    "snapshots": [
      {
        "date": "2026-04-23",
        "status": "ready",
        "usableRows": 1240,
        "indexedRows": 1300
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtracker ads

Returns the Meta ads for one active workspace brandtracker resolved from brandtracker.id to fb_page_id. The response reuses the public ad summary shape.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

sortBy?string

Sort key. The adOrder value also accepts ad_order and ad-order aliases.

status?string

Status filter for this request. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

Value in"all" | "image" | "video"

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

minDaysRunning?integer

Range0 <= value

maxDaysRunning?integer

Range0 <= value

minDuplicates?integer

Range0 <= value

maxDuplicates?integer

Range0 <= value

landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes for ad copy descriptions.

adCountries?string

Comma-separated country include/exclude filters.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?boolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

cpm?number

CPM used to convert spend filters into reach thresholds.

Default9

Range0.01 <= value

minSpend?number

Range0 <= value

maxSpend?number

Range0 <= value

spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

Range0 <= value

maxSpendPerPage?number

Range0 <= value

spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer

Range0 <= value

maxAge?integer

Range0 <= value

sex?string

Enum value accepted by this request. Allowed values: men, women, all.

Value in"men" | "women" | "all"

minFacebookLikes?integer

Range0 <= value

maxFacebookLikes?integer

Range0 <= value

minInstagramFollowers?integer

Range0 <= value

maxInstagramFollowers?integer

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

minDescriptionLength?integer

Range0 <= value

maxDescriptionLength?integer

Range0 <= value

linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Formatdate

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/ads"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "facebook_123456789",
      "collationId": "3810635369204881",
      "platform": "facebook",
      "status": "active",
      "createdAt": "2026-04-18T12:30:00.000Z",
      "firstSeenAt": "2026-04-10T00:00:00.000Z",
      "lastSeenAt": "2026-04-19T00:00:00.000Z",
      "daysRunning": 9,
      "media": {
        "type": "video",
        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
      },
      "advertiser": {
        "id": "1234567890",
        "name": "Example Brand",
        "logoUrl": "https://cdn.example.com/pages/example-brand.png",
        "facebookPageId": "1234567890",
        "liveAdsCount": 42,
        "reach30d": 152340,
        "totalReach": 842100,
        "countriesCount": 8,
        "facebookLikes": 125000,
        "instagramFollowers": 89000
      },
      "content": {
        "title": "Summer Sale",
        "body": "Up to 30% off selected products.",
        "transcript": "Save 30% on every order.",
        "callToAction": "Shop now",
        "landingPageUrl": "https://example.com/products/summer-sale",
        "landingPageDomain": "example.com",
        "ctaDescription": "Free shipping on orders over $50.",
        "ctaLinkDescription": "Shop the full collection"
      },
      "metrics": {
        "reach": 152340,
        "aggregatedReach": 284100,
        "estimatedSpend": 4262,
        "duplicates": 4,
        "reachDelta1d": 1200,
        "reachDelta7d": 8200,
        "reachDelta30d": 38400
      },
      "audience": {
        "targetedCountries": [
          "US",
          "FR"
        ],
        "mainCountry": "US",
        "gender": "all",
        "ageMin": 18,
        "ageMax": 65
      },
      "rank": {
        "positionInPage": 3,
        "currentRank": 12,
        "rankDelta": -4,
        "improvementPct": 0.25
      },
      "flags": {
        "isEuAd": true,
        "isLowReach": false,
        "isMediaChanged": false,
        "hasPartnerBadge": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtracker partnership ads

Returns deduped Meta partnership ad groups for one active workspace brandtracker. This endpoint always filters to ads with a partner badge and reuses the public ad summary shape.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

sortBy?string

Sort key. The adOrder value also accepts ad_order and ad-order aliases.

status?string

Status filter for this request. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

Value in"all" | "image" | "video"

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

minDaysRunning?integer

Range0 <= value

maxDaysRunning?integer

Range0 <= value

minDuplicates?integer

Range0 <= value

maxDuplicates?integer

Range0 <= value

landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes for ad copy descriptions.

adCountries?string

Comma-separated country include/exclude filters.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

cpm?number

CPM used to convert spend filters into reach thresholds.

Default9

Range0.01 <= value

minSpend?number

Range0 <= value

maxSpend?number

Range0 <= value

spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

Range0 <= value

maxSpendPerPage?number

Range0 <= value

spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer

Range0 <= value

maxAge?integer

Range0 <= value

sex?string

Enum value accepted by this request. Allowed values: men, women, all.

Value in"men" | "women" | "all"

minFacebookLikes?integer

Range0 <= value

maxFacebookLikes?integer

Range0 <= value

minInstagramFollowers?integer

Range0 <= value

maxInstagramFollowers?integer

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

minDescriptionLength?integer

Range0 <= value

maxDescriptionLength?integer

Range0 <= value

linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Formatdate

partnerId?string

Single partner identifier alias. It is merged with partnerIds when both are provided.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/partnership-ads"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "facebook_123456789",
      "collationId": "3810635369204881",
      "platform": "facebook",
      "status": "active",
      "createdAt": "2026-04-18T12:30:00.000Z",
      "firstSeenAt": "2026-04-10T00:00:00.000Z",
      "lastSeenAt": "2026-04-19T00:00:00.000Z",
      "daysRunning": 9,
      "media": {
        "type": "video",
        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
      },
      "advertiser": {
        "id": "1234567890",
        "name": "Example Brand",
        "logoUrl": "https://cdn.example.com/pages/example-brand.png",
        "facebookPageId": "1234567890",
        "liveAdsCount": 42,
        "reach30d": 152340,
        "totalReach": 842100,
        "countriesCount": 8,
        "facebookLikes": 125000,
        "instagramFollowers": 89000
      },
      "content": {
        "title": "Summer Sale",
        "body": "Up to 30% off selected products.",
        "transcript": "Save 30% on every order.",
        "callToAction": "Shop now",
        "landingPageUrl": "https://example.com/products/summer-sale",
        "landingPageDomain": "example.com",
        "ctaDescription": "Free shipping on orders over $50.",
        "ctaLinkDescription": "Shop the full collection"
      },
      "metrics": {
        "reach": 152340,
        "aggregatedReach": 284100,
        "estimatedSpend": 4262,
        "duplicates": 4,
        "reachDelta1d": 1200,
        "reachDelta7d": 8200,
        "reachDelta30d": 38400
      },
      "audience": {
        "targetedCountries": [
          "US",
          "FR"
        ],
        "mainCountry": "US",
        "gender": "all",
        "ageMin": 18,
        "ageMax": 65
      },
      "rank": {
        "positionInPage": 3,
        "currentRank": 12,
        "rankDelta": -4,
        "improvementPct": 0.25
      },
      "flags": {
        "isEuAd": true,
        "isLowReach": false,
        "isMediaChanged": false,
        "hasPartnerBadge": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Count brandtracker partnership ads

Returns the deduped public ad group count matching the partnership ads list filters. This intentionally matches public list pagination semantics rather than the webapp raw active badge count.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier backed by brandtracker.id. Legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

status?string

Status filter for this request. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

Value in"all" | "image" | "video"

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

minDaysRunning?integer

Range0 <= value

maxDaysRunning?integer

Range0 <= value

minDuplicates?integer

Range0 <= value

maxDuplicates?integer

Range0 <= value

landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes for ad copy descriptions.

adCountries?string

Comma-separated country include/exclude filters.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

cpm?number

CPM used to convert spend filters into reach thresholds.

Default9

Range0.01 <= value

minSpend?number

Range0 <= value

maxSpend?number

Range0 <= value

spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

Range0 <= value

maxSpendPerPage?number

Range0 <= value

spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer

Range0 <= value

maxAge?integer

Range0 <= value

sex?string

Enum value accepted by this request. Allowed values: men, women, all.

Value in"men" | "women" | "all"

minFacebookLikes?integer

Range0 <= value

maxFacebookLikes?integer

Range0 <= value

minInstagramFollowers?integer

Range0 <= value

maxInstagramFollowers?integer

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

minDescriptionLength?integer

Range0 <= value

maxDescriptionLength?integer

Range0 <= value

linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Formatdate

partnerId?string

Single partner identifier alias. It is merged with partnerIds when both are provided.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/1e08fa85-625a-4ba5-b673-d2a4b7bc7c55/partnership-ads/count"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "count": 0
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker hooks

Returns grouped hook analytics for the requested brandtracker using the authenticated workspace as the only access scope.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional hook sorting. Defaults to usageCount.

Value in"usageCount" | "longestRunning" | "totalImpressions" | "firstUsedAt" | "lastUsedAt"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/hooks"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "hook": "Stop scrolling.",
      "usageCount": 12,
      "longestRunning": 47,
      "totalImpressions": 152340,
      "firstUsedAt": "2026-02-01T09:12:00.000Z",
      "lastUsedAt": "2026-04-19T12:30:00.000Z",
      "sampleAd": {
        "adId": "facebook_123456789",
        "mediaUrl": "https://cdn.example.com/ads/creative.mp4",
        "thumbnailUrl": "https://cdn.example.com/ads/creative-thumb.jpg",
        "fullText": "This is the full transcript text for the sampled ad."
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker transcripts

Returns grouped transcript/script analytics for the requested brandtracker using the authenticated workspace as the only access scope.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional transcript sorting. Defaults to usageCount.

Value in"usageCount" | "longestRunning" | "totalImpressions" | "firstUsedAt" | "lastUsedAt"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/transcripts"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "fullText": "This is the full transcript text used by multiple ads in this brandtracker.",
      "usageCount": 12,
      "longestRunning": 47,
      "totalImpressions": 152340,
      "firstUsedAt": "2026-02-01T09:12:00.000Z",
      "lastUsedAt": "2026-04-19T12:30:00.000Z",
      "sampleAd": {
        "adId": "facebook_123456789",
        "mediaUrl": "https://cdn.example.com/ads/creative.mp4",
        "thumbnailUrl": "https://cdn.example.com/ads/creative-thumb.jpg"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker headlines

Returns grouped headline analytics for the requested brandtracker.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional headline sorting. Defaults to usageCount.

Value in"usageCount" | "longestRunning"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/headlines"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "headline": "Summer sale is live",
      "usageCount": 18,
      "longestRunning": 52
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker ad copies

Returns grouped ad copy analytics for the requested brandtracker.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional ad copy sorting. Defaults to usageCount.

Value in"usageCount" | "longestRunning"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/ad-copies"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "adCopy": "Get 30% off selected products this week only.",
      "usageCount": 21,
      "longestRunning": 43
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker landing pages

Returns grouped landing page analytics for the requested brandtracker, including detected technologies when available.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional landing page sorting. Defaults to usageCount.

Value in"usageCount" | "longestRunning" | "totalImpressions"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/landing-pages"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "landingPage": "https://example.com/products/summer-sale",
      "usageCount": 16,
      "longestRunning": 41,
      "totalImpressions": 305400,
      "technologies": [
        {
          "id": "04504d0b-df46-4f62-98b6-d4d9e14a2282",
          "name": "Shopify",
          "iconUrl": "https://cdn.example.com/technology_icons/shopify.svg"
        }
      ],
      "screenshots": {
        "desktop": "https://cdn.example.com/screenshots/landing-page-full.png",
        "mobile": "https://cdn.example.com/screenshots/landing-page-mobile.png",
        "head": "https://cdn.example.com/screenshots/landing-page-head.png"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get normalized brandtracker landing pages

Returns normalized/grouped landing page analytics for the requested brandtracker. Query strings, fragments, trailing slashes, and leading www. hostnames are ignored for grouping.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional normalized landing page sorting. Defaults to usageCount.

Value in"usageCount" | "activeAdsCount"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/landing-pages/simple"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "landingPage": "https://example.com/products/summer-sale",
      "normalizedLandingPage": "example.com/products/summer-sale",
      "usageCount": 16,
      "activeAdsCount": 5,
      "technologies": [
        {
          "id": "04504d0b-df46-4f62-98b6-d4d9e14a2282",
          "name": "Shopify",
          "iconUrl": "https://cdn.example.com/technology_icons/shopify.svg"
        }
      ],
      "screenshots": {
        "desktop": "https://cdn.example.com/screenshots/landing-page-full.png",
        "mobile": "https://cdn.example.com/screenshots/landing-page-mobile.png",
        "head": "https://cdn.example.com/screenshots/landing-page-head.png"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker creatives

Returns paginated creative analytics for the requested brandtracker.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional creatives sorting. Defaults to firstSeenAt.

Value in"firstSeenAt" | "daysRunning" | "duplicates"

mediaType?string

Optional media type filter. Defaults to all.

Value in"all" | "image" | "video"

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/creatives"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "adId": "facebook_123456789",
      "mediaType": "video",
      "mediaUrl": "https://cdn.example.com/ads/creative.mp4",
      "thumbnailUrl": "https://cdn.example.com/ads/creative-thumb.jpg",
      "firstSeenAt": "2026-03-01T08:00:00.000Z",
      "daysRunning": 27,
      "duplicates": 4
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker partners

Returns paginated partnership analytics for the requested brandtracker.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

timePeriod?string

Relative insights time window. Use stable windows like last7d or last30d for consistent agent behavior.

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

order?string

Optional sort order. Defaults to desc.

Value in"asc" | "desc"

snapshotDate?string

Optional snapshot anchor date (YYYY-MM-DD). When provided, the requested window is evaluated against that snapshot date.

Formatdate

sortBy?string

Optional partners sorting. Defaults to activeAds.

Value in"activeAds" | "launchDate" | "reach" | "estimatedSpend"

cpm?number

Optional CPM used to estimate spend from reach. Defaults to 9.

Default9

Range0 <= value

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/partners"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "facebookPageId": "61554990830184",
      "name": "Example Partner",
      "activeAds": 8,
      "launchDate": "2026-02-18T13:40:00.000Z",
      "reach": 245000,
      "estimatedSpend": 2205
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker media mix

Returns the media-format breakdown (image, video, dco, other) for the brandtracker's deduped currently active ads, or a deduped snapshot reconstruction when a snapshotDate is provided. activeAds equals the sum of the media buckets.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

snapshotDate?string

Optional snapshot date (YYYY-MM-DD or latest). When provided, the mix is reconstructed for that date; otherwise it uses live active ads. Counts are deduped by ad before media buckets are calculated.

Formatdate

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/media-mix"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "activeAds": 23,
    "formatCount": {
      "image": 12,
      "video": 8,
      "dco": 2,
      "other": 1
    }
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker demography

Returns the EU country / age / gender reach distributions precomputed for the brandtracker. The underlying dataset is page-level and EU-only, so this endpoint is fundamentally EU-scoped.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

euOnly?boolean

EU-only filter. This endpoint is fundamentally EU-scoped (the source data is the EU-only fb_page_reach_by_country table), so this defaults to true and is retained for forward compatibility.

Defaulttrue

snapshotDate?string

Optional snapshot date (YYYY-MM-DD or latest). The underlying demography data is currently a precomputed per-page snapshot (not time-windowed), so this parameter is accepted for forward compatibility but does not filter the result today.

Formatdate

timePeriod?string

Optional time window. The underlying demography data is currently a precomputed per-page snapshot (not time-windowed), so this parameter is accepted for forward compatibility but does not filter the result today.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/demography"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "hasData": true,
    "countryDistribution": [
      {
        "countryCode": "US",
        "reach": 125000
      }
    ],
    "ageDistribution": [
      {
        "ageRange": "25-34",
        "reach": 82000
      }
    ],
    "genderDistribution": [
      {
        "gender": "female",
        "reach": 91000
      }
    ]
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get current ranked top ads

Canonical current-ranking endpoint for a brandtracker. Use sortBy=currentRank for the current Facebook page rank, sortBy=reach/reachDelta1d/reachDelta7d/reachDelta30d for reach rankings, and sortBy=rankDelta7d/rankDelta14d/rankDelta30d for rank movers. period and snapshotDate are deprecated compatibility parameters and are ignored on this current-ranking path.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

facebookPageId?string

Optional Facebook page id belonging to this brandtracker. When omitted, the primary Facebook page is used.

Lengthlength <= 64

allFacebookPages?boolean

When true, aggregate all selected Facebook pages. Current ranks are page-local, so ties across pages are expected. Cannot be combined with facebookPageId.

Defaultfalse

euOnly?boolean

Optional EU-only filter. When true, only EU-classified Facebook ads are included.

Defaultfalse

sortBy?string

Sort key for canonical current rankings. Use currentRank for the selected Facebook page rank (returned as rank/currentRank); rankDelta7d, rankDelta14d, or rankDelta30d for movers; reach, reachDelta1d, reachDelta7d, or reachDelta30d for reach rankings.

Value in

"currentRank" | "rankDelta" | "rankDelta7d" | "rankDelta14d" | "rankDelta30d" | "reach" | "reachDelta1d" | "reachDelta7d" | "reachDelta30d" | "daysRunning" | "duplicates"

status?string

Preferred activity filter. active returns active ads, inactive returns inactive ads, all returns both. When supplied, it takes precedence over includeInactive.

Value in"active" | "inactive" | "all"

includeInactive?booleanDeprecated

Deprecated. When status is omitted, includeInactive=true maps to status=all; ignored when status is supplied.

Defaultfalse

period?string

Optional rolling top-ads period. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.

snapshotDate?|Deprecated

Deprecated compatibility parameter accepted but ignored by canonical top-ads current ranking. Use freshness/system endpoints for snapshot availability checks.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/top-ads"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "ad": {
        "id": "facebook_123456789",
        "collationId": "3810635369204881",
        "platform": "facebook",
        "status": "active",
        "createdAt": "2026-04-18T12:30:00.000Z",
        "firstSeenAt": "2026-04-10T00:00:00.000Z",
        "lastSeenAt": "2026-04-19T00:00:00.000Z",
        "daysRunning": 9,
        "media": {
          "type": "video",
          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
        },
        "advertiser": {
          "id": "1234567890",
          "name": "Example Brand",
          "logoUrl": "https://cdn.example.com/pages/example-brand.png",
          "facebookPageId": "1234567890",
          "liveAdsCount": 42,
          "reach30d": 152340,
          "totalReach": 842100,
          "countriesCount": 8,
          "facebookLikes": 125000,
          "instagramFollowers": 89000
        },
        "content": {
          "title": "Summer Sale",
          "body": "Up to 30% off selected products.",
          "transcript": "Save 30% on every order.",
          "callToAction": "Shop now",
          "landingPageUrl": "https://example.com/products/summer-sale",
          "landingPageDomain": "example.com",
          "ctaDescription": "Free shipping on orders over $50.",
          "ctaLinkDescription": "Shop the full collection"
        },
        "metrics": {
          "reach": 152340,
          "aggregatedReach": 284100,
          "estimatedSpend": 4262,
          "duplicates": 4,
          "reachDelta1d": 1200,
          "reachDelta7d": 8200,
          "reachDelta30d": 38400
        },
        "audience": {
          "targetedCountries": [
            "US",
            "FR"
          ],
          "mainCountry": "US",
          "gender": "all",
          "ageMin": 18,
          "ageMax": 65
        },
        "rank": {
          "positionInPage": 3,
          "currentRank": 12,
          "rankDelta": -4,
          "improvementPct": 0.25
        },
        "flags": {
          "isEuAd": true,
          "isLowReach": false,
          "isMediaChanged": false,
          "hasPartnerBadge": true
        }
      },
      "metrics": {
        "totalReach": 152340,
        "duplicateCount": 4,
        "daysRunning": 27,
        "currentRank": 3
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "reason": "no_snapshot_for_period"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker ad rank compatibility data

Compatibility endpoint for clients that still call /ad-rank. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

timeWindow?string

Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.

Value in"last7d" | "last14d" | "last30d" | "7d" | "14d" | "30d"

sortBy?string

Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.

Value in"rankDelta" | "currentRank" | "rank_delta" | "current_rank"

snapshotDate?stringDeprecated

Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.

Formatdate

maxCurrentRank?integer

Optional maximum current rank filter. Only ads at or above this current rank are returned.

Range1 <= value

minRankDelta?integer

Minimum positive rank improvement required for an ad to be returned. Defaults to 1.

Default1

Range1 <= value

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/ad-rank"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "ad": {
        "id": "facebook_123456789",
        "collationId": "3810635369204881",
        "platform": "facebook",
        "status": "active",
        "createdAt": "2026-04-18T12:30:00.000Z",
        "firstSeenAt": "2026-04-10T00:00:00.000Z",
        "lastSeenAt": "2026-04-19T00:00:00.000Z",
        "daysRunning": 9,
        "media": {
          "type": "video",
          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
        },
        "advertiser": {
          "id": "1234567890",
          "name": "Example Brand",
          "logoUrl": "https://cdn.example.com/pages/example-brand.png",
          "facebookPageId": "1234567890",
          "liveAdsCount": 42,
          "reach30d": 152340,
          "totalReach": 842100,
          "countriesCount": 8,
          "facebookLikes": 125000,
          "instagramFollowers": 89000
        },
        "content": {
          "title": "Summer Sale",
          "body": "Up to 30% off selected products.",
          "transcript": "Save 30% on every order.",
          "callToAction": "Shop now",
          "landingPageUrl": "https://example.com/products/summer-sale",
          "landingPageDomain": "example.com",
          "ctaDescription": "Free shipping on orders over $50.",
          "ctaLinkDescription": "Shop the full collection"
        },
        "metrics": {
          "reach": 152340,
          "aggregatedReach": 284100,
          "estimatedSpend": 4262,
          "duplicates": 4,
          "reachDelta1d": 1200,
          "reachDelta7d": 8200,
          "reachDelta30d": 38400
        },
        "audience": {
          "targetedCountries": [
            "US",
            "FR"
          ],
          "mainCountry": "US",
          "gender": "all",
          "ageMin": 18,
          "ageMax": 65
        },
        "rank": {
          "positionInPage": 3,
          "currentRank": 12,
          "rankDelta": -4,
          "improvementPct": 0.25
        },
        "flags": {
          "isEuAd": true,
          "isLowReach": false,
          "isMediaChanged": false,
          "hasPartnerBadge": true
        }
      },
      "metrics": {
        "currentRank": 4,
        "previousRank": 17,
        "rankDelta": 13,
        "improvementPct": 76.5
      },
      "trajectory": [
        {
          "date": "2026-04-20",
          "rank": 4,
          "totalAds": 250
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker scaling ads compatibility data

Legacy compatibility endpoint for clients that still call /scaling-ads. Prefer /v1/brandtrackers/{brandtrackerId}/top-ads?sortBy=rankDelta7d, rankDelta14d, or rankDelta30d for canonical rank movers and sortBy=currentRank for current ranking. Endpoint key, billing, and response envelope remain stable; snapshotDate is deprecated and ignored on the ES-backed path, and trajectory may be empty.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of items to return. Defaults to 20.

Default20

Range1 <= value <= 50

timeWindow?string

Scaling comparison window. Prefer stable windows (last7d or last14d) for agent workflows.

Value in"last7d" | "last14d" | "last30d" | "7d" | "14d" | "30d"

sortBy?string

Optional scaling ads sort key. Defaults to rankDelta. Also accepts legacy aliases rank_delta and current_rank.

Value in"rankDelta" | "currentRank" | "rank_delta" | "current_rank"

snapshotDate?stringDeprecated

Deprecated compatibility parameter accepted but ignored on the ES-backed compatibility path. Use top-ads sortBy=rankDelta7d/14d/30d for canonical rank movers.

Formatdate

maxCurrentRank?integer

Optional maximum current rank filter. Only ads at or above this current rank are returned.

Range1 <= value

minRankDelta?integer

Minimum positive rank improvement required for an ad to be returned. Defaults to 1.

Default1

Range1 <= value

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/scaling-ads"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "ad": {
        "id": "facebook_123456789",
        "collationId": "3810635369204881",
        "platform": "facebook",
        "status": "active",
        "createdAt": "2026-04-18T12:30:00.000Z",
        "firstSeenAt": "2026-04-10T00:00:00.000Z",
        "lastSeenAt": "2026-04-19T00:00:00.000Z",
        "daysRunning": 9,
        "media": {
          "type": "video",
          "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
          "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
        },
        "advertiser": {
          "id": "1234567890",
          "name": "Example Brand",
          "logoUrl": "https://cdn.example.com/pages/example-brand.png",
          "facebookPageId": "1234567890",
          "liveAdsCount": 42,
          "reach30d": 152340,
          "totalReach": 842100,
          "countriesCount": 8,
          "facebookLikes": 125000,
          "instagramFollowers": 89000
        },
        "content": {
          "title": "Summer Sale",
          "body": "Up to 30% off selected products.",
          "transcript": "Save 30% on every order.",
          "callToAction": "Shop now",
          "landingPageUrl": "https://example.com/products/summer-sale",
          "landingPageDomain": "example.com",
          "ctaDescription": "Free shipping on orders over $50.",
          "ctaLinkDescription": "Shop the full collection"
        },
        "metrics": {
          "reach": 152340,
          "aggregatedReach": 284100,
          "estimatedSpend": 4262,
          "duplicates": 4,
          "reachDelta1d": 1200,
          "reachDelta7d": 8200,
          "reachDelta30d": 38400
        },
        "audience": {
          "targetedCountries": [
            "US",
            "FR"
          ],
          "mainCountry": "US",
          "gender": "all",
          "ageMin": 18,
          "ageMax": 65
        },
        "rank": {
          "positionInPage": 3,
          "currentRank": 12,
          "rankDelta": -4,
          "improvementPct": 0.25
        },
        "flags": {
          "isEuAd": true,
          "isLowReach": false,
          "isMediaChanged": false,
          "hasPartnerBadge": true
        }
      },
      "metrics": {
        "currentRank": 4,
        "previousRank": 17,
        "rankDelta": 13,
        "improvementPct": 76.5
      },
      "trajectory": [
        {
          "date": "2026-04-20",
          "rank": 4,
          "totalAds": 250
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker ad copy evolution

Returns graph-ready ad copy evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide adCopy for exact single-text mode, or omit it to page through bounded global series ranked by active ads.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number for global mode. Exact mode always returns at most one series.

Default1

Range1 <= value

limit?integer

Number of series to return in global mode. Exact mode costs and returns one series.

Default10

Range1 <= value <= 25

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date.

Formatdate

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided.

Formatdate

snapshotDate?string

Optional snapshot date. When provided, it is used as the effective end date.

Formatdate

adCopy?string

Exact ad copy text to return as a single evolution series. Omit for global mode.

Lengthlength <= 5000

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/ad-copy-evolution"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "dateRange": {
    "startDate": "2026-01-01",
    "endDate": "2026-04-20"
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  },
  "data": [
    {
      "adCopy": "Turn your mornings into a ritual.",
      "points": [
        {
          "date": "2026-04-20",
          "recordedAt": "2026-04-20T12:30:00.000Z",
          "activeAds": 12,
          "totalAds": 48,
          "euAds": 9,
          "euActiveAds": 7,
          "totalReach": 124500,
          "percentNewAds": 18.5
        }
      ]
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker headline evolution

Returns graph-ready headline evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide headline for exact single-text mode, or omit it to page through bounded global series ranked by active ads.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number for global mode. Exact mode always returns at most one series.

Default1

Range1 <= value

limit?integer

Number of series to return in global mode. Exact mode costs and returns one series.

Default10

Range1 <= value <= 25

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date.

Formatdate

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided.

Formatdate

snapshotDate?string

Optional snapshot date. When provided, it is used as the effective end date.

Formatdate

headline?string

Exact headline text to return as a single evolution series. Omit for global mode.

Lengthlength <= 1000

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/headline-evolution"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "dateRange": {
    "startDate": "2026-01-01",
    "endDate": "2026-04-20"
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  },
  "data": [
    {
      "headline": "The ritual your skin was waiting for",
      "points": [
        {
          "date": "2026-04-20",
          "recordedAt": "2026-04-20T12:30:00.000Z",
          "activeAds": 12,
          "totalAds": 48,
          "euAds": 9,
          "euActiveAds": 7,
          "totalReach": 124500,
          "percentNewAds": 18.5
        }
      ]
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker landing page evolution

Returns graph-ready landing page evolution series for one active workspace brandtracker resolved from brandtracker.id. Provide landingPage for exact single-page mode, or omit it to page through bounded global series ranked by active ads.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Pagination page number for global mode. Exact mode always returns at most one series.

Default1

Range1 <= value

limit?integer

Number of series to return in global mode. Exact mode costs and returns one series.

Default10

Range1 <= value <= 25

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date.

Formatdate

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided.

Formatdate

snapshotDate?string

Optional snapshot date. When provided, it is used as the effective end date.

Formatdate

landingPage?string

Exact landing page URL to return as a single evolution series. Omit for global mode.

Lengthlength <= 2048

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/landing-page-evolution"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "dateRange": {
    "startDate": "2026-01-01",
    "endDate": "2026-04-20"
  },
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 128,
    "totalPages": 7
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  },
  "data": [
    {
      "landingPage": "https://example.com/products/ritual-kit",
      "points": [
        {
          "date": "2026-04-20",
          "recordedAt": "2026-04-20T12:30:00.000Z",
          "activeAds": 12,
          "totalAds": 48,
          "euAds": 9,
          "euActiveAds": 7,
          "totalReach": 124500,
          "percentNewAds": 18.5
        }
      ]
    }
  ]
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker time-series

Returns graph-ready Brandtracker time-series for ads launched, live ads history, and EU impression/spend deltas. Use period for rolling windows, or startDate/endDate for explicit ranges; do not combine period with date params.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

granularity?string

Bucket size for the returned graph data. Defaults to daily.

Value in"daily" | "weekly" | "monthly"

startDate?string

Inclusive start date. Defaults to 365 days before the effective end date. Cannot be combined with period.

Formatdate

endDate?string

Inclusive end date. Defaults to today unless snapshotDate is provided. Cannot be combined with period.

Formatdate

snapshotDate?string

Optional snapshot date. When provided with period, it anchors the rolling window; otherwise it is used as the effective end date.

Formatdate

period?string

Optional rolling window for the time-series. Supports today, yesterday, 1d, 7d, 14d, 30d, 90d, and 365d. Cannot be combined with startDate or endDate; snapshotDate may anchor the window.

Value in"today" | "yesterday" | "1d" | "7d" | "14d" | "30d" | "90d" | "365d"

euOnly?boolean

When true, only EU-classified ads are counted for adsLaunched.

Defaultfalse

cpm?number

CPM used to estimate spend from EU impression deltas.

Default9

Range0.01 <= value <= 10000

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/time-series"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "granularity": "daily",
    "dateRange": {
      "startDate": "2026-01-01",
      "endDate": "2026-04-20"
    },
    "adsLaunched": [
      {
        "date": "2026-04-20",
        "count": 12
      }
    ],
    "liveAds": [
      {
        "date": "2026-04-20",
        "count": 12
      }
    ],
    "euImpressionsSpend": [
      {
        "date": "2026-04-20",
        "impressions": 12450,
        "cumulativeImpressions": 431200,
        "estimatedSpend": 112.05
      }
    ],
    "cpm": 9
  },
  "meta": {
    "requestedSnapshotDate": "latest",
    "resolvedSnapshotDate": "2026-04-23",
    "dataFreshnessLagDays": 1,
    "periodNote": "period=today uses the latest ready completed snapshot date instead of partial current-day data."
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtracker timeline ads

Returns timeline-ready Meta ads for one active workspace brandtracker resolved from brandtracker.id. Timeline membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Default1

Range1 <= value

limit?integer

Default50

Range1 <= value <= 100

sortBy?string

Sort key for this request. Allowed values: newest, createdAt, longestRunning, reach, duplicates, adOrder, relevance.

status?string

Status filter for this request. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

Value in"all" | "image" | "video"

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

minDaysRunning?integer

Range0 <= value

maxDaysRunning?integer

Range0 <= value

minDuplicates?integer

Range0 <= value

maxDuplicates?integer

Range0 <= value

landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.

adCountries?string

Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?boolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

cpm?number

CPM used to convert spend filters into reach thresholds.

Default9

Range0.01 <= value

minSpend?number

Range0 <= value

maxSpend?number

Range0 <= value

spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

Range0 <= value

maxSpendPerPage?number

Range0 <= value

spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer

Range0 <= value

maxAge?integer

Range0 <= value

sex?string

Enum value accepted by this request. Allowed values: men, women, all.

Value in"men" | "women" | "all"

minFacebookLikes?integer

Range0 <= value

maxFacebookLikes?integer

Range0 <= value

minInstagramFollowers?integer

Range0 <= value

maxInstagramFollowers?integer

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

minDescriptionLength?integer

Range0 <= value

maxDescriptionLength?integer

Range0 <= value

linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Formatdate

startedAfter?string

Inclusive ad start-date lower bound.

Formatdate

startedBefore?string

Inclusive ad start-date upper bound.

Formatdate

lastSeenAfter?string

Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.

Formatdate

lastSeenBefore?string

Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.

Formatdate

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/timeline"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": "facebook_123456789",
      "collationId": "3810635369204881",
      "platform": "facebook",
      "status": "active",
      "createdAt": "2026-04-18T12:30:00.000Z",
      "firstSeenAt": "2026-04-10T00:00:00.000Z",
      "lastSeenAt": "2026-04-19T00:00:00.000Z",
      "daysRunning": 9,
      "media": {
        "type": "video",
        "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
        "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
      },
      "advertiser": {
        "id": "1234567890",
        "name": "Example Brand",
        "logoUrl": "https://cdn.example.com/pages/example-brand.png",
        "facebookPageId": "1234567890",
        "liveAdsCount": 42,
        "reach30d": 152340,
        "totalReach": 842100,
        "countriesCount": 8,
        "facebookLikes": 125000,
        "instagramFollowers": 89000
      },
      "content": {
        "title": "Summer Sale",
        "body": "Up to 30% off selected products.",
        "transcript": "Save 30% on every order.",
        "callToAction": "Shop now",
        "landingPageUrl": "https://example.com/products/summer-sale",
        "landingPageDomain": "example.com",
        "ctaDescription": "Free shipping on orders over $50.",
        "ctaLinkDescription": "Shop the full collection"
      },
      "metrics": {
        "reach": 152340,
        "aggregatedReach": 284100,
        "estimatedSpend": 4262,
        "duplicates": 4,
        "reachDelta1d": 1200,
        "reachDelta7d": 8200,
        "reachDelta30d": 38400
      },
      "audience": {
        "targetedCountries": [
          "US",
          "FR"
        ],
        "mainCountry": "US",
        "gender": "all",
        "ageMin": 18,
        "ageMax": 65
      },
      "rank": {
        "positionInPage": 3,
        "currentRank": 12,
        "rankDelta": -4,
        "improvementPct": 0.25
      },
      "flags": {
        "isEuAd": true,
        "isLowReach": false,
        "isMediaChanged": false,
        "hasPartnerBadge": true
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker timeline metadata

Returns total count and date bounds for the same filter membership used by the brandtracker timeline endpoint.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

status?string

Status filter for this request. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

Value in"all" | "image" | "video"

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"

createdAfter?string

Formatdate-time

createdBefore?string

Formatdate-time

minDaysRunning?integer

Range0 <= value

maxDaysRunning?integer

Range0 <= value

minDuplicates?integer

Range0 <= value

maxDuplicates?integer

Range0 <= value

landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.

adCountries?string

Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?boolean

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?integer

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

maxReach?integer

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

cpm?number

CPM used to convert spend filters into reach thresholds.

Default9

Range0.01 <= value

minSpend?number

Range0 <= value

maxSpend?number

Range0 <= value

spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?number

Range0 <= value

maxSpendPerPage?number

Range0 <= value

spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?integer

Range0 <= value

maxAge?integer

Range0 <= value

sex?string

Enum value accepted by this request. Allowed values: men, women, all.

Value in"men" | "women" | "all"

minFacebookLikes?integer

Range0 <= value

maxFacebookLikes?integer

Range0 <= value

minInstagramFollowers?integer

Range0 <= value

maxInstagramFollowers?integer

Range0 <= value

minVideoDuration?number

Range0 <= value

maxVideoDuration?number

Range0 <= value

minDescriptionLength?integer

Range0 <= value

maxDescriptionLength?integer

Range0 <= value

linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Formatdate

startedAfter?string

Inclusive ad start-date lower bound.

Formatdate

startedBefore?string

Inclusive ad start-date upper bound.

Formatdate

lastSeenAfter?string

Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.

Formatdate

lastSeenBefore?string

Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.

Formatdate

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/timeline/metadata"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "totalCount": 235,
    "earliestDate": "2026-04-01",
    "latestDate": "2026-04-23"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List brandtracker creative testing batches

Returns creative-testing batches grouped by ad start date for one active workspace brandtracker resolved from brandtracker.id. Testing membership includes non-deleted Facebook ads with media available in the bucket and a non-null start date. To keep response size and metering bounded, each batch returns at most 20 ads and exposes truncation metadata.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

page?integer

Batch page number. Pagination is by distinct ad start-date batches.

Default1

Range1 <= value

limit?integer

Number of distinct start-date batches to return. Each batch returns at most 20 ads.

Default25

Range1 <= value <= 50

status?string

Status filter for this request. Allowed values: all, active, inactive.

Value in"all" | "active" | "inactive"

mediaType?string

Enum value accepted by this request. Allowed values: all, image, video.

Value in"all" | "image" | "video"

keywords?array<string>

Keyword search terms. Repeated query params and comma-separated values are both accepted.

keywordMode?string

Enum value accepted by this request. Allowed values: any, all.

Value in"any" | "all"

createdAfter?|

Formatdate-time

createdBefore?|

Formatdate-time

minDaysRunning?|

Range0 <= value

maxDaysRunning?|

Range0 <= value

minDuplicates?|

Range0 <= value

maxDuplicates?|

Range0 <= value

landingPages?array<string>

Landing page URLs. Repeated query params and comma-separated values are both accepted.

adLanguage?array<string>

Ad languages. Repeated query params and comma-separated values are both accepted.

cta?array<string>

Call-to-action labels. Repeated query params and comma-separated values are both accepted.

adCopyHashes?array<string>

12-character MD5 prefixes of ad copy descriptions. Repeated query params and comma-separated values are both accepted.

adCountries?string

Ad country include/exclude filter. Use comma-separated ISO codes with include/exclude modes.

mainCountries?array<string>

Main ad countries. Repeated query params and comma-separated values are both accepted.

euOnly?boolean

When true, keep only ads flagged as EU ads.

partners?|

When true, keep only partnership ads. When false, keep only non-partnership ads.

partnerIds?array<string>

Partner identifiers. Repeated query params and comma-separated values are both accepted.

minReach?|

Minimum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

maxReach?|

Maximum ad reach threshold. Backed by the internal reach/impressions analytics field.

Range0 <= value

cpm?number

CPM used to convert spend filters into reach thresholds.

Default9

Range0.01 <= value

minSpend?|

Range0 <= value

maxSpend?|

Range0 <= value

spendPeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

minSpendPerPage?|

Range0 <= value

maxSpendPerPage?|

Range0 <= value

spendPerPagePeriod?string

Enum value accepted by this request. Allowed values: total, last24h, last7d, last30d.

Value in"total" | "last24h" | "last7d" | "last30d"

hideLowReach?boolean

When true, hides ads flagged as low reach.

minAge?|

Range0 <= value

maxAge?|

Range0 <= value

sex?string

Enum value accepted by this request. Allowed values: men, women, all.

Value in"men" | "women" | "all"

minFacebookLikes?|

Range0 <= value

maxFacebookLikes?|

Range0 <= value

minInstagramFollowers?|

Range0 <= value

maxInstagramFollowers?|

Range0 <= value

minVideoDuration?|

Range0 <= value

maxVideoDuration?|

Range0 <= value

minDescriptionLength?|

Range0 <= value

maxDescriptionLength?|

Range0 <= value

linkedDomain?string

Linked domain filter. URLs are normalized to their hostname before validation.

growthRank?array<>

Rank trend filters. Repeated query params and comma-separated values are both accepted.

snapshotDate?string

Snapshot date (YYYY-MM-DD or latest). When present, status is interpreted as active at this date.

Formatdate

startedAfter?string

Inclusive ad start-date lower bound.

Formatdate

startedBefore?string

Inclusive ad start-date upper bound.

Formatdate

lastSeenAfter?string

Inclusive effective timeline end-date lower bound. Active ads use today, or snapshotDate when provided.

Formatdate

lastSeenBefore?string

Inclusive effective timeline end-date upper bound. Active ads use today, or snapshotDate when provided.

Formatdate

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/testing"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "startDate": "2026-04-20",
      "ads": [
        {
          "id": "facebook_123456789",
          "collationId": "3810635369204881",
          "platform": "facebook",
          "status": "active",
          "createdAt": "2026-04-18T12:30:00.000Z",
          "firstSeenAt": "2026-04-10T00:00:00.000Z",
          "lastSeenAt": "2026-04-19T00:00:00.000Z",
          "daysRunning": 9,
          "media": {
            "type": "video",
            "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
            "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
          },
          "advertiser": {
            "id": "1234567890",
            "name": "Example Brand",
            "logoUrl": "https://cdn.example.com/pages/example-brand.png",
            "facebookPageId": "1234567890",
            "liveAdsCount": 42,
            "reach30d": 152340,
            "totalReach": 842100,
            "countriesCount": 8,
            "facebookLikes": 125000,
            "instagramFollowers": 89000
          },
          "content": {
            "title": "Summer Sale",
            "body": "Up to 30% off selected products.",
            "transcript": "Save 30% on every order.",
            "callToAction": "Shop now",
            "landingPageUrl": "https://example.com/products/summer-sale",
            "landingPageDomain": "example.com",
            "ctaDescription": "Free shipping on orders over $50.",
            "ctaLinkDescription": "Shop the full collection"
          },
          "metrics": {
            "reach": 152340,
            "aggregatedReach": 284100,
            "estimatedSpend": 4262,
            "duplicates": 4,
            "reachDelta1d": 1200,
            "reachDelta7d": 8200,
            "reachDelta30d": 38400
          },
          "audience": {
            "targetedCountries": [
              "US",
              "FR"
            ],
            "mainCountry": "US",
            "gender": "all",
            "ageMin": 18,
            "ageMax": 65
          },
          "rank": {
            "positionInPage": 3,
            "currentRank": 12,
            "rankDelta": -4,
            "improvementPct": 0.25
          },
          "flags": {
            "isEuAd": true,
            "isLowReach": false,
            "isMediaChanged": false,
            "hasPartnerBadge": true
          }
        }
      ],
      "adsReturned": 20,
      "maxAdsPerBatch": 20,
      "adsTruncated": false,
      "runningCount": 1,
      "isWinner": true,
      "stats": {
        "reach": {
          "min": 1200,
          "avg": 4200,
          "max": 9800,
          "total": 16800
        },
        "daysRunning": {
          "min": 2,
          "avg": 12,
          "max": 31
        },
        "activeCount": 2,
        "totalCount": 4,
        "bestPerformerId": "facebook_123456789"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 73,
    "totalPages": 3
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get brandtracker overview

Returns a dashboard-style Brandtracker overview combining graph, media mix, top landing pages, top ads, and ads preview sections. The graph accepts timeSeriesPeriod for rolling windows or timeSeriesStartDate/timeSeriesEndDate for explicit ranges; do not combine them.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

brandtrackerId*string

Public brandtracker identifier. This endpoint resolves brandtracker.id inside the authenticated workspace; legacy spyders.uuid values are accepted when migration metadata exists.

Query Parameters

euOnly?boolean

Optional EU-only filter forwarded to graph, media mix, landing pages, and top ads sections where supported.

Defaultfalse

snapshotDate?|

Snapshot date for dashboard time travel. Use YYYY-MM-DD or latest.

cpm?number

CPM used to estimate spend in the graph section.

Default9

Range0.01 <= value <= 10000

timeSeriesGranularity?string

Bucket size for the graph section. Defaults to daily.

Value in"daily" | "weekly" | "monthly"

timeSeriesStartDate?string

Inclusive graph start date. Cannot be combined with timeSeriesPeriod.

Formatdate

timeSeriesEndDate?string

Inclusive graph end date. Cannot be combined with timeSeriesPeriod.

Formatdate

timeSeriesPeriod?string

Optional rolling window for the graph section. Supports today, yesterday, 1d, 7d, 14d, 30d, 90d, and 365d. Cannot be combined with timeSeriesStartDate or timeSeriesEndDate; snapshotDate may anchor the window.

Value in"today" | "yesterday" | "1d" | "7d" | "14d" | "30d" | "90d" | "365d"

landingPagesTimePeriod?string

Time window for top landing pages. Defaults to live for dashboard-style current overview.

landingPagesLimit?integer

Maximum number of top landing pages to return. Defaults to 5.

Default5

Range1 <= value <= 20

topAdsLimit?integer

Maximum number of top ads to return. Defaults to 5.

Default5

Range1 <= value <= 20

adsPreviewLimit?integer

Maximum number of ads preview items to return. Defaults to 10.

Default10

Range1 <= value <= 50

topAdsSortBy?string

Optional top ads sorting. Defaults to reach when euOnly=true, otherwise daysRunning.

Value in

"currentRank" | "rankDelta" | "rankDelta7d" | "rankDelta14d" | "rankDelta30d" | "reach" | "reachDelta1d" | "reachDelta7d" | "reachDelta30d" | "daysRunning" | "duplicates"

topAdsPeriod?string

Optional top ads period. Supports today, yesterday, last1d, last7d, last14d, last30d, and total. Defaults to total.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/brandtrackers/string/overview"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "graph": {
      "granularity": "daily",
      "dateRange": {
        "startDate": "2026-01-01",
        "endDate": "2026-04-20"
      },
      "adsLaunched": [
        {
          "date": "2026-04-20",
          "count": 12
        }
      ],
      "liveAds": [
        {
          "date": "2026-04-20",
          "count": 12
        }
      ],
      "euImpressionsSpend": [
        {
          "date": "2026-04-20",
          "impressions": 12450,
          "cumulativeImpressions": 431200,
          "estimatedSpend": 112.05
        }
      ],
      "cpm": 9
    },
    "mediaMix": {
      "activeAds": 23,
      "formatCount": {
        "image": 12,
        "video": 8,
        "dco": 2,
        "other": 1
      }
    },
    "topLandingPages": {
      "data": [
        {
          "landingPage": "https://example.com/products/summer-sale",
          "usageCount": 16,
          "longestRunning": 41,
          "totalImpressions": 305400,
          "technologies": [
            {
              "id": "04504d0b-df46-4f62-98b6-d4d9e14a2282",
              "name": "Shopify",
              "iconUrl": "https://cdn.example.com/technology_icons/shopify.svg"
            }
          ],
          "screenshots": {
            "desktop": "https://cdn.example.com/screenshots/landing-page-full.png",
            "mobile": "https://cdn.example.com/screenshots/landing-page-mobile.png",
            "head": "https://cdn.example.com/screenshots/landing-page-head.png"
          }
        }
      ],
      "pagination": {
        "page": 1,
        "limit": 20,
        "total": 128,
        "totalPages": 7
      }
    },
    "topAds": {
      "data": [
        {
          "ad": {
            "id": "facebook_123456789",
            "collationId": "3810635369204881",
            "platform": "facebook",
            "status": "active",
            "createdAt": "2026-04-18T12:30:00.000Z",
            "firstSeenAt": "2026-04-10T00:00:00.000Z",
            "lastSeenAt": "2026-04-19T00:00:00.000Z",
            "daysRunning": 9,
            "media": {
              "type": "video",
              "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
              "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
            },
            "advertiser": {
              "id": "1234567890",
              "name": "Example Brand",
              "logoUrl": "https://cdn.example.com/pages/example-brand.png",
              "facebookPageId": "1234567890",
              "liveAdsCount": 42,
              "reach30d": 152340,
              "totalReach": 842100,
              "countriesCount": 8,
              "facebookLikes": 125000,
              "instagramFollowers": 89000
            },
            "content": {
              "title": "Summer Sale",
              "body": "Up to 30% off selected products.",
              "transcript": "Save 30% on every order.",
              "callToAction": "Shop now",
              "landingPageUrl": "https://example.com/products/summer-sale",
              "landingPageDomain": "example.com",
              "ctaDescription": "Free shipping on orders over $50.",
              "ctaLinkDescription": "Shop the full collection"
            },
            "metrics": {
              "reach": 152340,
              "aggregatedReach": 284100,
              "estimatedSpend": 4262,
              "duplicates": 4,
              "reachDelta1d": 1200,
              "reachDelta7d": 8200,
              "reachDelta30d": 38400
            },
            "audience": {
              "targetedCountries": [
                "US",
                "FR"
              ],
              "mainCountry": "US",
              "gender": "all",
              "ageMin": 18,
              "ageMax": 65
            },
            "rank": {
              "positionInPage": 3,
              "currentRank": 12,
              "rankDelta": -4,
              "improvementPct": 0.25
            },
            "flags": {
              "isEuAd": true,
              "isLowReach": false,
              "isMediaChanged": false,
              "hasPartnerBadge": true
            }
          },
          "metrics": {
            "totalReach": 152340,
            "duplicateCount": 4,
            "daysRunning": 27,
            "currentRank": 3
          }
        }
      ],
      "pagination": {
        "page": 1,
        "limit": 20,
        "total": 128,
        "totalPages": 7
      }
    },
    "adsPreview": {
      "data": [
        {
          "id": "facebook_123456789",
          "collationId": "3810635369204881",
          "platform": "facebook",
          "status": "active",
          "createdAt": "2026-04-18T12:30:00.000Z",
          "firstSeenAt": "2026-04-10T00:00:00.000Z",
          "lastSeenAt": "2026-04-19T00:00:00.000Z",
          "daysRunning": 9,
          "media": {
            "type": "video",
            "thumbnailUrl": "https://cdn.example.com/ads/ad-1-thumb.jpg",
            "mediaUrl": "https://cdn.example.com/ads/ad-1.mp4"
          },
          "advertiser": {
            "id": "1234567890",
            "name": "Example Brand",
            "logoUrl": "https://cdn.example.com/pages/example-brand.png",
            "facebookPageId": "1234567890",
            "liveAdsCount": 42,
            "reach30d": 152340,
            "totalReach": 842100,
            "countriesCount": 8,
            "facebookLikes": 125000,
            "instagramFollowers": 89000
          },
          "content": {
            "title": "Summer Sale",
            "body": "Up to 30% off selected products.",
            "transcript": "Save 30% on every order.",
            "callToAction": "Shop now",
            "landingPageUrl": "https://example.com/products/summer-sale",
            "landingPageDomain": "example.com",
            "ctaDescription": "Free shipping on orders over $50.",
            "ctaLinkDescription": "Shop the full collection"
          },
          "metrics": {
            "reach": 152340,
            "aggregatedReach": 284100,
            "estimatedSpend": 4262,
            "duplicates": 4,
            "reachDelta1d": 1200,
            "reachDelta7d": 8200,
            "reachDelta30d": 38400
          },
          "audience": {
            "targetedCountries": [
              "US",
              "FR"
            ],
            "mainCountry": "US",
            "gender": "all",
            "ageMin": 18,
            "ageMax": 65
          },
          "rank": {
            "positionInPage": 3,
            "currentRank": 12,
            "rankDelta": -4,
            "improvementPct": 0.25
          },
          "flags": {
            "isEuAd": true,
            "isLowReach": false,
            "isMediaChanged": false,
            "hasPartnerBadge": true
          }
        }
      ],
      "pagination": {
        "page": 1,
        "limit": 25,
        "total": 235,
        "totalPages": 10
      }
    }
  },
  "meta": {}
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`