Brand leaderboard (who AI answers mention, and how often)

curl --request POST \
  --url https://app.geoly.ai/api/v1/reports/brand-board \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "time_range": "30d",
  "start_date": "<string>",
  "end_date": "<string>",
  "topic_ids": [
    "<string>"
  ],
  "country": "<string>",
  "limit": 20,
  "include_trend": false
}
'

import requests

url = "https://app.geoly.ai/api/v1/reports/brand-board"

payload = {
    "time_range": "30d",
    "start_date": "<string>",
    "end_date": "<string>",
    "topic_ids": ["<string>"],
    "country": "<string>",
    "limit": 20,
    "include_trend": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    time_range: '30d',
    start_date: '<string>',
    end_date: '<string>',
    topic_ids: ['<string>'],
    country: '<string>',
    limit: 20,
    include_trend: false
  })
};

fetch('https://app.geoly.ai/api/v1/reports/brand-board', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "mode": "confirmed",
    "status": "ok",
    "caliber": "tracked_brand_v1",
    "reason": "<string>",
    "brand": {
      "id": "<string>",
      "name": "<string>"
    },
    "window": {
      "time_range": "7d",
      "start_at": "2023-11-07T05:31:56Z",
      "end_at": "2023-11-07T05:31:56Z",
      "end_bounded": true
    },
    "platform": "<string>",
    "scope": {
      "active": true,
      "topic_ids": [
        "<string>"
      ],
      "country": "<string>",
      "collapsed": true
    },
    "completed_records": 1,
    "completed_source": "tracked",
    "own_brand": {
      "name": "<string>",
      "mention_rate_pct": 50,
      "share_pct": 50,
      "mentioned_records": 1,
      "rank": 1,
      "pending": true,
      "computing": true
    },
    "mention_rate_leaders": [
      "<string>"
    ],
    "rows": [
      {
        "rank": 1,
        "entity_id": "<string>",
        "name": "<string>",
        "source": "manual",
        "mention_rate_pct": 50,
        "share_pct": 50,
        "mentioned_records": 1,
        "computing": true
      }
    ],
    "total": 1,
    "returned": 1,
    "coverage": {
      "floor_date": "<string>",
      "window_start_date": "<string>",
      "clamped": true
    },
    "unmapped": [
      {
        "name": "<string>"
      }
    ],
    "trend": [
      {
        "business_date": "<string>",
        "brand_mention_rate_pct": 50,
        "completed_records": 1,
        "brand_mentioned_records": 1,
        "competitors": [
          {
            "entity_id": "<string>",
            "name": "<string>",
            "mention_rate_pct": 50,
            "mentioned_records": 1
          }
        ]
      }
    ],
    "trend_competitors": [
      {
        "entity_id": "<string>",
        "name": "<string>"
      }
    ],
    "trend_meta": {
      "days": 1,
      "truncated": true,
      "first_date": "<string>",
      "latest_date": "<string>"
    }
  },
  "page": {
    "next_cursor": null,
    "limit": 123
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "schema_conformant": true,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

Reports

Brand board

Your brand and the competitors you track, ranked by mention rate in the window (caliber “tracked_brand_v1”; untracked brands never appear, rank is among tracked brands only). data.mode is “confirmed” for every filter combination (“scoped_open_world” is no longer returned); data.status says whether the board is ready (not_ready while the brand’s first count is still running). GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).

POST

api

reports

brand-board

Brand leaderboard (who AI answers mention, and how often)

curl --request POST \
  --url https://app.geoly.ai/api/v1/reports/brand-board \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "time_range": "30d",
  "start_date": "<string>",
  "end_date": "<string>",
  "topic_ids": [
    "<string>"
  ],
  "country": "<string>",
  "limit": 20,
  "include_trend": false
}
'

import requests

url = "https://app.geoly.ai/api/v1/reports/brand-board"

payload = {
    "time_range": "30d",
    "start_date": "<string>",
    "end_date": "<string>",
    "topic_ids": ["<string>"],
    "country": "<string>",
    "limit": 20,
    "include_trend": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    time_range: '30d',
    start_date: '<string>',
    end_date: '<string>',
    topic_ids: ['<string>'],
    country: '<string>',
    limit: 20,
    include_trend: false
  })
};

fetch('https://app.geoly.ai/api/v1/reports/brand-board', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "mode": "confirmed",
    "status": "ok",
    "caliber": "tracked_brand_v1",
    "reason": "<string>",
    "brand": {
      "id": "<string>",
      "name": "<string>"
    },
    "window": {
      "time_range": "7d",
      "start_at": "2023-11-07T05:31:56Z",
      "end_at": "2023-11-07T05:31:56Z",
      "end_bounded": true
    },
    "platform": "<string>",
    "scope": {
      "active": true,
      "topic_ids": [
        "<string>"
      ],
      "country": "<string>",
      "collapsed": true
    },
    "completed_records": 1,
    "completed_source": "tracked",
    "own_brand": {
      "name": "<string>",
      "mention_rate_pct": 50,
      "share_pct": 50,
      "mentioned_records": 1,
      "rank": 1,
      "pending": true,
      "computing": true
    },
    "mention_rate_leaders": [
      "<string>"
    ],
    "rows": [
      {
        "rank": 1,
        "entity_id": "<string>",
        "name": "<string>",
        "source": "manual",
        "mention_rate_pct": 50,
        "share_pct": 50,
        "mentioned_records": 1,
        "computing": true
      }
    ],
    "total": 1,
    "returned": 1,
    "coverage": {
      "floor_date": "<string>",
      "window_start_date": "<string>",
      "clamped": true
    },
    "unmapped": [
      {
        "name": "<string>"
      }
    ],
    "trend": [
      {
        "business_date": "<string>",
        "brand_mention_rate_pct": 50,
        "completed_records": 1,
        "brand_mentioned_records": 1,
        "competitors": [
          {
            "entity_id": "<string>",
            "name": "<string>",
            "mention_rate_pct": 50,
            "mentioned_records": 1
          }
        ]
      }
    ],
    "trend_competitors": [
      {
        "entity_id": "<string>",
        "name": "<string>"
      }
    ],
    "trend_meta": {
      "days": 1,
      "truncated": true,
      "first_date": "<string>",
      "latest_date": "<string>"
    }
  },
  "page": {
    "next_cursor": null,
    "limit": 123
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "schema_conformant": true,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

Authorizations

Authorization

string

header

required

API key from Settings → Developer → API keys (prefix geom_). Each key is bound to one brand.

Body

application/json

time_range

enum<string>

default:30d

Rolling window, or "custom" with start_date + end_date. 180d is billed at twice the base price.

Available options:

7d,

30d,

90d,

180d,

custom

start_date

string

Start of a custom window (UTC+8 business day, YYYY-MM-DD).

Pattern: ^\d{4}-\d{2}-\d{2}$

end_date

string

End of a custom window (UTC+8 business day, YYYY-MM-DD).

Pattern: ^\d{4}-\d{2}-\d{2}$

platform

enum<string>

AI platform; omit for all platforms. Combines freely with topic_ids / country.

Available options:

chatgpt,

perplexity,

gemini,

google_ai,

copilot,

google_ai_overview

topic_ids

string[]

Restrict to these topic ids (1–50). "_none" = prompts without a topic.

Required array length: 1 - 50 elements

Required string length: 1 - 64

country

string

ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.

Required string length: 1 - 8

limit

integer

default:20

Top-N rows (1–50).

Required range: 1 <= x <= 50

include_trend

boolean

default:false

Also return the daily mention-rate trend (confirmed mode only).

Response

The brand-board report. data follows BrandBoardReport when meta.schema_conformant is true.

data

object

required

The brand-board report. null only when meta.schema_conformant is false and the report output could not be mapped.

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

page

object

required

Top-N report: only limit; next_cursor is always null.

Show child attributes

Get started

Account

Catalog

Records

Reports

Brand board

Authorizations

Body

Response