OTotterly
Brand Reports

Create a brand report

Changed on

Creates a brand report in a workspace, the same as creating it in the UI. The prompts must already exist in that workspace — create them with POST /v1/workspaces/{id}/prompts — and the report tracks their countries. Domains are normalized (protocol, www. and path stripped). Detect the brand either by brand and brandVariations, or by brandRegex together with reportTitle. Competitors can come straight from POST /v1/competitors/suggestions. Data for the report is collected asynchronously. Sending the same request again within 2 minutes returns the report the first request created instead of a second one; if that report is still being set up, the response is a 409 carrying its ID.

post/v1/reports/brand

Request

  • Base URL
    https://data.otterly.ai
  • Auth
    HTTP bearer

Request body

workspaceIdstring required

Workspace to create the report in. The API key must have access to it.

reportTitlestring

Optional. Report name shown in the app. Defaults to brand. Required when brandRegex is set.

brandstring

Brand name to track. Required unless brandRegex is set, in which case reportTitle is used as the brand label.

brandVariationsstring[]

Optional. Other names the brand goes by, at most 100. Cannot be combined with brandRegex.

brandDomainstring required

Brand website domain, e.g. acme.com. Protocol, www. and path are stripped.

brandDomainVariationsstring[]

Optional. Other domains the brand owns, at most 100. Each must differ from brandDomain.

brandDomainWildcardboolean

Optional. When true, subdomains of brandDomain also count as the brand domain.

brandRegexstring nullable

Optional. Regular expression used to detect the brand in AI answers, instead of the name and its variations (so it cannot be combined with brandVariations). Up to 1000 characters. Send null to clear it.

promptIdsstring[] required

IDs of prompts that already exist in the report workspace — look them up with GET /v1/workspaces/{id}/prompts. The report tracks the countries of these prompts.

Example request

{
  "workspaceId": "01HX7K2YV9D3M8N0G6Q5R4S3T2",
  "reportTitle": "Adidas Visibility Report",
  "brand": "Adidas",
  "brandDomain": "adidas.com",
  "promptIds": [
    "01HXP1DRTM5G8Z2N3KQ7VAW4PA"
  ],
  "competitors": [
    {
      "brand": "Nike",
      "brandDomain": "nike.com"
    }
  ]
}

Response

The created brand report.

idstring required
workspaceIdstring required
brandstring required
reportTitlestring
brandVariationsstring[]
brandDomainstring required
brandDomainVariationsstring[]
brandDomainWildcardboolean
brandRegexstring nullable required

Regular expression used to detect the brand in AI answers, instead of brand and brandVariations. null when not set.

countriesstring[] required

Lowercase ISO 3166-1 alpha-2 country codes the report tracks (e.g. us, de), with uk used in place of gb.

createdDatestring required
updatedDatestring required
promptIdsstring[]
countryPromptsTotalobject

Total prompt count keyed by country code (lowercase ISO 3166-1 alpha-2; uk instead of gb).

Example response

{
  "id": "01HXBR1DGM5XY8Z2N3KQ7VAW4P",
  "workspaceId": "01HX7K2YV9D3M8N0G6Q5R4S3T2",
  "brand": "Adidas",
  "brandVariations": [
    "adidas",
    "Adidas AG"
  ],
  "brandDomain": "adidas.com",
  "brandDomainVariations": [
    "adidas.de",
    "adidas.co.uk"
  ],
  "brandDomainWildcard": false,
  "brandRegex": null,
  "countries": [
    "us",
    "de",
    "uk"
  ],
  "competitors": [
    {
      "brand": "Nike",
      "brandVariations": [
        "nike",
        "Nike Inc."
      ],
      "brandDomain": "nike.com",
      "brandDomainVariations": [
        "nike.de",
        "nike.co.uk"
      ],
      "brandDomainWildcard": false,
      "brandRegex": null
    }
  ],
  "reportTitle": "Adidas Visibility Report",
  "createdDate": "2024-11-01T12:00:00.000Z",
  "updatedDate": "2025-05-01T08:30:00.000Z",
  "promptIds": [
    "01HXP1DRTM5G8Z2N3KQ7VAW4PA",
    "01HXP2DRTM5G8Z2N3KQ7VAW4PB"
  ],
  "countryPromptsTotal": {
    "us": 50,
    "de": 35,
    "uk": 28
  },
  "tags": [
    {
      "id": "01HX8AB3CDE4FG5HJ6KL7MN8PQ",
      "name": "Running Shoes",
      "color": "orange"
    }
  ]
}

Changes