Introducción | Documentación de la API pública de Trendtrack

List workspace brandtracker folders

Returns the active workspace brandtracker folders so clients can resolve folderIds for workspace and brandtracker filters. Folder names are returned as metadata; prefer folderIds for exact filtering. Equivalent folder listing is also available at GET /v1/brandtrackers/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/workspace/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"
          ]
        }
      ]
    }
  }
}

Inspect the authenticated workspace

Returns the workspace bound to the provided public API key along with the effective authentication context.

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/workspace"

{
  "requestId": "38558568-a304-4682-a798-2578e37345f0",
  "workspace": {
    "id": "ws_123",
    "slug": "my-workspace",
    "name": "My Workspace",
    "createdAt": "2024-11-12T16:12:43.931Z"
  },
  "authenticatedAs": {
    "accessLevel": "full_access",
    "delegatedUserId": null,
    "delegatedUserRole": null
  },
  "credential": {
    "id": "cred_123",
    "name": "Production key",
    "description": null,
    "expiresAt": null,
    "createdAt": "2026-04-20T07:24:00.246Z",
    "lastUsedAt": "2026-04-20T07:28:18.682Z"
  }
}

{
  "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 workspace top ads

Canonical current-ranking endpoint across active workspace brandtrackers in a single metered request. Each returned row is explicitly nested as { brandtracker, ad, metrics }. Billing remains proportional to requested/returned row count (limit/result length), not brandtracker count. Use sortBy=currentRank for 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

Query Parameters

page?integer

Pagination page number. Defaults to 1.

Default1

Range1 <= value

limit?integer

Maximum number of workspace top ads to return. Must be <= 100.

Default20

Range1 <= value <= 100

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 current 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"

includeInactive?boolean

When true, include inactive ads where supported. Defaults to false.

Defaultfalse

period?string

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

snapshotDate?|Deprecated

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

Response Body

`application/json`

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

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "brandtracker": {
        "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
        "name": "Acme",
        "facebookPageId": "123456789012345"
      },
      "ad": {
        "id": "facebook_123456789",
        "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"
          ]
        }
      ]
    }
  }
}

Get workspace hooks

Returns hook analytics aggregated across active workspace brandtrackers in one metered request. One credit is charged per returned row.

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

Maximum number of workspace aggregate rows to return. Must be <= 100.

Default20

Range1 <= value <= 100

brandtrackerIds?array<string>

Optional comma-separated or repeated public brandtracker ids.

folderIds?array<integer>

Optional comma-separated or repeated workspace brandtracker folder ids.

euOnly?boolean

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

Defaultfalse

order?string

Value in"asc" | "desc"

sortBy?string

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

Response Body

`application/json`

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

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "brandtracker": {
        "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
        "name": "Acme",
        "facebookPageId": "123456789012345"
      },
      "hook": {
        "text": "Stop scrolling.",
        "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."
        }
      },
      "metrics": {
        "usageCount": 12,
        "longestRunning": 47,
        "totalImpressions": 152340,
        "firstUsedAt": "2019-08-24T14:15:22Z",
        "lastUsedAt": "2019-08-24T14:15:22Z"
      }
    }
  ],
  "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"
          ]
        }
      ]
    }
  }
}

Get workspace ad copies

Returns ad copy analytics aggregated across active workspace brandtrackers in one metered request. One credit is charged per returned row.

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

Maximum number of workspace aggregate rows to return. Must be <= 100.

Default20

Range1 <= value <= 100

brandtrackerIds?array<string>

Optional comma-separated or repeated public brandtracker ids.

folderIds?array<integer>

Optional comma-separated or repeated workspace brandtracker folder ids.

euOnly?boolean

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

Defaultfalse

order?string

Value in"asc" | "desc"

sortBy?string

Value in"usageCount" | "longestRunning"

Response Body

`application/json`

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

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "brandtracker": {
        "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
        "name": "Acme",
        "facebookPageId": "123456789012345"
      },
      "adCopy": {
        "text": "Get 30% off selected products this week only."
      },
      "metrics": {
        "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"
          ]
        }
      ]
    }
  }
}

Get workspace landing pages

Returns landing page analytics aggregated across active workspace brandtrackers in one metered request. One credit is charged per returned row.

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

Maximum number of workspace aggregate rows to return. Must be <= 100.

Default20

Range1 <= value <= 100

brandtrackerIds?array<string>

Optional comma-separated or repeated public brandtracker ids.

folderIds?array<integer>

Optional comma-separated or repeated workspace brandtracker folder ids.

euOnly?boolean

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

Defaultfalse

order?string

Value in"asc" | "desc"

sortBy?string

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

Response Body

`application/json`

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

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "brandtracker": {
        "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
        "name": "Acme",
        "facebookPageId": "123456789012345"
      },
      "landingPage": {
        "url": "https://example.com/products/summer-sale",
        "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"
        }
      },
      "metrics": {
        "usageCount": 16,
        "longestRunning": 41,
        "totalImpressions": 305400
      }
    }
  ],
  "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"
          ]
        }
      ]
    }
  }
}

Get workspace scaling ads compatibility data

Legacy compatibility endpoint for clients that still call /workspace/scaling-ads. Prefer /v1/workspace/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; period and snapshotDate are deprecated and ignored on the ES-backed path, and trajectory may be empty. One credit is charged per returned row.

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

Maximum number of workspace aggregate rows to return. Must be <= 100.

Default20

Range1 <= value <= 100

brandtrackerIds?array<string>

Optional comma-separated or repeated public brandtracker ids.

folderIds?array<integer>

Optional comma-separated or repeated workspace brandtracker folder ids.

euOnly?boolean

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

Defaultfalse

period?string

Optional rolling period for workspace scaling ads. Allowed values: today, yesterday, last1d, last7d, last14d, last30d, total.

snapshotDate?|Deprecated

Deprecated compatibility parameter accepted but ignored on the ES-backed workspace scaling compatibility path. Use freshness/system endpoints for snapshot availability checks.

sortBy?string

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

maxCurrentRank?integer

Range1 <= value

minRankDelta?integer

Default1

Range1 <= value

Response Body

`application/json`

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

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "brandtracker": {
        "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
        "name": "Acme",
        "facebookPageId": "123456789012345"
      },
      "ad": {
        "id": "facebook_123456789",
        "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
  }
}

{
  "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 workspace media mix

Returns media mix rows across active workspace brandtrackers in one metered request. One credit is charged per returned row.

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

Maximum number of workspace aggregate rows to return. Must be <= 100.

Default20

Range1 <= value <= 100

brandtrackerIds?array<string>

Optional comma-separated or repeated public brandtracker ids.

folderIds?array<integer>

Optional comma-separated or repeated workspace brandtracker folder ids.

euOnly?boolean

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

Defaultfalse

sortBy?string

Value in"activeAds" | "image" | "video" | "dco" | "other"

Response Body

`application/json`

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

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "brandtracker": {
        "id": "1e08fa85-625a-4ba5-b673-d2a4b7bc7c55",
        "name": "Acme",
        "facebookPageId": "123456789012345"
      },
      "mediaMix": {
        "formatCount": {
          "image": 12,
          "video": 8,
          "dco": 2,
          "other": 1
        }
      },
      "metrics": {
        "activeAds": 23
      }
    }
  ],
  "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"
          ]
        }
      ]
    }
  }
}

Workspace

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

500application/json

503application/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`