Skip to content
TrakkrLearnAPI
Sign in

Brands and markets

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

Code example

List Brands
curl -X GET 'https://api.trakkr.ai/get-brands?include=markets%2Caliases' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
Response · 200 OK (with include)
{
  "brands": [
    {
      "id": "00000000-0000-4000-8000-81f286d10c3c",
      "name": "Nike",
      "website": "https://nike.com",
      "favicon": "https://www.google.com/s2/favicons?domain=nike.com&sz=64",
      "active": true,
      "role": "owner",
      "aliases": ["Nike Inc", "Nike.com", "Nike Running"],
      "markets": [
        {
          "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
          "location": "US",
          "is_primary": true,
          "active": true,
          "created_at": "2026-01-15T10:00:00Z"
        },
        {
          "id": "m9a8b7c6-d5e4-3210-abcd-ef0987654321",
          "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
          "location": "GB",
          "is_primary": false,
          "active": true,
          "created_at": "2026-02-20T14:30:00Z"
        }
      ]
    }
  ]
}

Synthetic example. Values are made up.

API key required

60 req/min

List Brands

GET/get-brands

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

Request parameters

brand_idstring | nullqueryOptional

Filter to a single brand by UUID

Format: uuid

includestring | nullqueryOptional

Comma-separated: markets, aliases, profile

Responses and errors
200Successful Response

application/json

brandsobject[]Required

Fields in brands

Array of object.

idstringRequired

namestringRequired

websitestring | nullOptional

faviconstring | nullOptional

activebooleanOptional

Default: true

rolestringOptional

Default: "owner" · Options: "owner", "editor", "viewer"

locationstring | nullOptional

location_regionstring | nullOptional

location_citystring | nullOptional

marketsobject[] | nullOptional

aliasesstring[] | nullOptional

descriptionstring | nullOptional

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source

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.

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.
Try GET /get-brands
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:

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.

Add Market

POST/get-brands/markets

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

JSON request body (required)

brand_idstringRequired

Format: uuid

locationstringRequired

market_namestring | nullOptional

languagestring | nullOptional

Question language (BCP-47), for example es or en-GB. Omit to inherit the brand language when creating a market. Existing market languages are never changed; use Replace market in brand settings to preserve history.

Responses and errors
201Successful Response

application/json

languagestring | nullOptional

Question language (BCP-47), independent of the country.

idstringRequired

brand_idstringRequired

locationstringRequired

location_regionstring | nullOptional

location_citystring | nullOptional

is_primarybooleanRequired

activebooleanRequired

created_atstringRequired

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source
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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

Request parameters

brand_idstringqueryRequired

Brand UUID

Format: uuid

market_idstringqueryRequired

Market UUID to remove

Responses and errors
200Successful Response

application/json

successbooleanRequired

deleted_idstringRequired

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

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

Market Examples

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

Synthetic example. Values are made up.

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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

JSON request body (required)

brand_idstringRequired

Format: uuid

countrystringRequired

location_regionstring | nullOptional

location_citystring | nullOptional

location_dataseo_codeinteger | nullOptional

Responses and errors
200Successful Response

application/json

brand_idstringRequired

locationstringRequired

location_regionstring | nullOptional

location_citystring | nullOptional

location_dataseo_codeinteger | nullOptional

primary_marketobject | nullOptional

Fields in primary_market
MarketItem

languagestring | nullOptional

Question language (BCP-47), independent of the country.

idstringRequired

brand_idstringRequired

locationstringRequired

location_regionstring | nullOptional

location_citystring | nullOptional

is_primarybooleanRequired

activebooleanRequired

created_atstringRequired

null

null.

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source
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
curl -X PUT 'https://api.trakkr.ai/get-brands/location' \
  -H "Authorization: Bearer $TRAKKR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"brand_id":"00000000-0000-4000-8000-81f286d10c3c","country":"GB"}'
Response · 200 OK
{
  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
  "location": "GB",
  "location_region": null,
  "location_city": null,
  "location_dataseo_code": null,
  "primary_market": {
    "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
    "location": "GB",
    "is_primary": true,
    "active": true,
    "created_at": "2026-05-28T10:00:00Z"
  }
}

Synthetic example. Values are made up.

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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

JSON request body (required)

brand_idstringRequired

Format: uuid

aliasesstring[]Required

Fields in aliases

Array of string.

string.

Responses and errors
200Successful Response

application/json

successbooleanRequired

brand_idstringRequired

aliasesstring[]Required

Fields in aliases

Array of string.

string.

reports_updatedintegerRequired

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source
This replaces all existing aliases. To add an alias, include the existing aliases plus the new one. Duplicates are automatically removed.
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
curl -X PUT 'https://api.trakkr.ai/get-brands/aliases' \
  -H "Authorization: Bearer $TRAKKR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"brand_id":"00000000-0000-4000-8000-81f286d10c3c","aliases":["Nike Inc","Nike.com","Nike Running"]}'
Response · 200 OK
{
  "success": true,
  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
  "aliases": ["Nike Inc", "Nike.com", "Nike Running"],
  "reports_updated": 42
}

Synthetic example. Values are made up.

Next Steps

After getting your brand IDs, you can: