Skip to content
TrakkrAPI

Get Brands

List brands, manage markets (geographic regions), and update aliases (alternate brand names).

Requires authentication
60 req/min

List Brands

GET/get-brands

Returns every brand your account can currently read through direct membership, a team grant, or an active client assignment. Restricted team grants are included only when they allow viewing. Client assignments always return the viewer role and cannot use write endpoints.

Query Parameters

brand_idstring

Filter to a single brand by UUID

includestring

Comma-separated: "markets", "aliases", "profile"

Without the include parameter, brands are returned with basic fields only. Add include=markets,aliases,profile to embed sub-resources in the response. profile adds the brand's own description. The favicon and location fields always come back, with no include needed.
Rate limit: 60 requests/minute for GET. Write operations (POST, PUT, DELETE) are limited to 30 requests/minute.
Errors on this page return {"detail": "..."}. The one exception is 429, which comes from the rate limiter and returns error instead. There is no retry_after field and no Retry-After header: wait a minute and retry.

Response Fields

Each brand in the response includes these fields:

Brand Object

idstring

Unique brand identifier (UUID)

namestring

Display name of the brand

websitestring

Brand website URL

faviconstringnullable

Favicon URL saved for the brand. Always returned; null if none was saved.

activeboolean

Whether the brand is active

rolestring

Your role: "owner", "editor", or "viewer"

locationstring

Primary market ISO-2 country code (e.g. "US", "GB"). Null if the brand is not geo-pinned (global mode).

location_regionstring

Primary market region/state, if set

location_citystring

Primary market city, if set

marketsarray

Markets (only when include=markets). Array of market objects.

aliasesarray

Brand aliases (only when include=aliases). Array of strings.

descriptionstringnullable

The brand's own description (only when include=profile).

Using Brand IDs

The id field is a unique identifier that you'll use in other API calls. Use it as the brand_id parameter:

GET /get-scores?brand_id=00000000-0000-4000-8000-81f286d10c3c

Markets

Markets represent geographic regions where your brand is tracked. Each brand has one primary market and can have additional markets depending on your plan.

Market Object

idstring

Market UUID

brand_idstring

Parent brand UUID

locationstring

ISO-2 country code (e.g. "US", "GB", "DE")

is_primaryboolean

Whether this is the primary market

activeboolean

Whether the market is active

created_atstring

ISO 8601 creation timestamp

Add Market

POST/get-brands/markets

Body Parameters

brand_idstringrequired

Brand UUID

locationstringrequired

ISO-2 country code (e.g. "US", "GB", "DE")

market_namestring

Optional display name for the market

The first market added to a brand automatically becomes the primary market. Use standard ISO-2 country codes (US, GB, DE, FR, JP, etc.).

Remove Market

DELETE/get-brands/markets

Query Parameters

brand_idstringrequired

Brand UUID

market_idstringrequired

Market UUID to remove

You cannot remove the primary market. Change the primary market in your brand settings first.

Market Examples

Add Market
Code language
1curl -X POST 'https://api.trakkr.ai/get-brands/markets' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{"brand_id": "00000000-0000-4000-8000-81f286d10c3c", "location": "GB"}'
Response example
1{
2  "id": "m9a8b7c6-d5e4-3210-abcd-ef0987654321",
3  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
4  "location": "GB",
5  "is_primary": false,
6  "active": true,
7  "created_at": "2026-03-07T10:00:00Z"
8}

Primary Location

Set a brand's primary market in one call. This pins the brand's home country (and optionally a region/city) so competitor analysis and AI search results are measured against the right market. A brand with no location runs in global mode, which can skew its competitor set toward US results.

PUT/get-brands/location

Body Parameters

brand_idstringrequired

Brand UUID

countrystringrequired

ISO-2 country code (e.g. "GB", "US", "DE"). The alias "UK" and full country names are also accepted.

location_regionstring

Optional region/state to narrow the market

location_citystring

Optional city to narrow the market further

location_dataseo_codenumber

Optional DataForSEO location code for precise sub-country targeting

Use standard ISO-2 country codes (US, GB, DE, FR, JP, etc.). The common aliasUK and full country names likeUnited Kingdom are also accepted. Updating the primary location reuses the brand's existing primary market, so it does not consume an extra-market add-on.
Set Primary Location
Code language
1curl -X PUT 'https://api.trakkr.ai/get-brands/location' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{"brand_id": "00000000-0000-4000-8000-81f286d10c3c", "country": "GB"}'
Response example
1{
2  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
3  "location": "GB",
4  "location_region": null,
5  "location_city": null,
6  "location_dataseo_code": null,
7  "primary_market": {
8    "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
9    "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
10    "location": "GB",
11    "is_primary": true,
12    "active": true,
13    "created_at": "2026-05-28T10:00:00Z"
14  }
15}

Aliases

Aliases are alternate names for your brand that get aggregated into your visibility score. For example, "Nike" might also appear as "Nike Inc", "Nike.com", or "Nike Running" in AI responses.

PUT/get-brands/aliases

Body Parameters

brand_idstringrequired

Brand UUID

aliasesstring[]required

Array of alias strings

This replaces all existing aliases. To add an alias, include the existing aliases plus the new one. Duplicates are automatically removed.

Response

successboolean

True when the aliases were saved

brand_idstring

The brand you updated

aliasesstring[]

The cleaned alias list now stored on the brand. Blanks and duplicates are stripped.

reports_updatedinteger

How many past reports were recounted with the new alias list

Changing aliases recounts your past reports, because a mention of a new alias now counts as a mention of the brand. reports_updated tells you how many reports were rewritten, so expect visibility numbers to move after this call.

Aliases Examples

Update Aliases
Code language
1curl -X PUT 'https://api.trakkr.ai/get-brands/aliases' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{"brand_id": "00000000-0000-4000-8000-81f286d10c3c", "aliases": ["Nike Inc", "Nike.com", "Nike Running"]}'
Response example
1{
2  "success": true,
3  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
4  "aliases": ["Nike Inc", "Nike.com", "Nike Running"],
5  "reports_updated": 42
6}

Next Steps

After getting your brand IDs, you can:

Code example

List Brands
Code language
1curl -H 'Authorization: Bearer $TRAKKR_API_KEY' \
2  'https://api.trakkr.ai/get-brands?include=markets,aliases'
Response example
1{
2  "brands": [
3    {
4      "id": "00000000-0000-4000-8000-81f286d10c3c",
5      "name": "Nike",
6      "website": "https://nike.com",
7      "favicon": "https://www.google.com/s2/favicons?domain=nike.com&sz=64",
8      "active": true,
9      "role": "owner",
10      "aliases": ["Nike Inc", "Nike.com", "Nike Running"],
11      "markets": [
12        {
13          "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
14          "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
15          "location": "US",
16          "is_primary": true,
17          "active": true,
18          "created_at": "2026-01-15T10:00:00Z"
19        },
20        {
21          "id": "m9a8b7c6-d5e4-3210-abcd-ef0987654321",
22          "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
23          "location": "GB",
24          "is_primary": false,
25          "active": true,
26          "created_at": "2026-02-20T14:30:00Z"
27        }
28      ]
29    }
30  ]
31}
Press ? for keyboard shortcuts