Citation source board (which domains AI answers cite)
curl --request POST \
--url https://app.geoly.ai/api/v1/reports/citations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"time_range": "30d",
"platform": "all",
"topic_ids": [
"<string>"
]
}
'import requests
url = "https://app.geoly.ai/api/v1/reports/citations"
payload = {
"time_range": "30d",
"platform": "all",
"topic_ids": ["<string>"]
}
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', platform: 'all', topic_ids: ['<string>']})
};
fetch('https://app.geoly.ai/api/v1/reports/citations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"status": "ready",
"reason": null,
"filtered": true,
"window": {
"time_range": "7d",
"days": 1,
"start_date": "<string>",
"end_date": "<string>",
"prev_start_date": "<string>",
"prev_end_date": "<string>",
"today_date": "<string>",
"closed_empty": true
},
"stats_caliber": "created_day",
"stats_window": {
"axis": "citation_created_day",
"timezone": "<string>",
"time_range": "7d",
"start_date": "<string>",
"end_date": "<string>",
"closed_end_date": "<string>",
"as_of_at": "2023-11-07T05:31:56Z"
},
"stats": {
"total_citations": 1,
"unique_root_domains": 1,
"daily": [
{
"business_date": "<string>",
"utc_date": "<string>",
"citations": 1,
"brand_citations": 1
}
],
"ownership": {
"brand_pct": 50,
"competitor_pct": 50,
"third_party_pct": 50,
"brand_owned_citations": 1,
"competitor_owned_citations": 1
},
"brand_subdomains": [
{
"domain": "<string>",
"citations": 1
}
],
"top_domains": [
{
"root_domain": "<string>",
"citations": 1,
"share_ratio": 0.5,
"is_brand_domain": true,
"domain_type": "you"
}
],
"platforms": [
{
"platform_code": "<string>",
"platform_name": "<string>",
"citations": 1,
"share_ratio": 0.5
}
]
},
"prev_ready": true,
"coverage": {
"ready_dates": [
"<string>"
],
"missing_dates": [
"<string>"
],
"as_of_at": "2023-11-07T05:31:56Z"
},
"invalid_filter": "competitors",
"totals": {
"root_domains": 1,
"citations": 1
},
"you": {
"root_domains": [
"<string>"
],
"citations": 1,
"share_ratio": 0.5,
"rank": 1
},
"movers": {
"top": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
],
"new": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
],
"up": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
],
"down": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
]
},
"entered_top20": [
"<string>"
],
"biggest_drop": {
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
},
"trend": {
"default_granularity": "day",
"business_dates": [
"<string>"
],
"series": [
{
"root_domain": "<string>",
"is_you": true,
"values": [
1
]
}
],
"first_date": "<string>"
},
"citations_by_type": {
"you": 1,
"competitor": 1,
"other": 1,
"total": 1
}
},
"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
Citations report
Top cited root domains with movers, your share, citation type split and the daily trend over closed business days. With a topic filter the whole-brand stats block is null and data.filtered is true. 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
/
v1
/
reports
/
citations
Citation source board (which domains AI answers cite)
curl --request POST \
--url https://app.geoly.ai/api/v1/reports/citations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"time_range": "30d",
"platform": "all",
"topic_ids": [
"<string>"
]
}
'import requests
url = "https://app.geoly.ai/api/v1/reports/citations"
payload = {
"time_range": "30d",
"platform": "all",
"topic_ids": ["<string>"]
}
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', platform: 'all', topic_ids: ['<string>']})
};
fetch('https://app.geoly.ai/api/v1/reports/citations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"status": "ready",
"reason": null,
"filtered": true,
"window": {
"time_range": "7d",
"days": 1,
"start_date": "<string>",
"end_date": "<string>",
"prev_start_date": "<string>",
"prev_end_date": "<string>",
"today_date": "<string>",
"closed_empty": true
},
"stats_caliber": "created_day",
"stats_window": {
"axis": "citation_created_day",
"timezone": "<string>",
"time_range": "7d",
"start_date": "<string>",
"end_date": "<string>",
"closed_end_date": "<string>",
"as_of_at": "2023-11-07T05:31:56Z"
},
"stats": {
"total_citations": 1,
"unique_root_domains": 1,
"daily": [
{
"business_date": "<string>",
"utc_date": "<string>",
"citations": 1,
"brand_citations": 1
}
],
"ownership": {
"brand_pct": 50,
"competitor_pct": 50,
"third_party_pct": 50,
"brand_owned_citations": 1,
"competitor_owned_citations": 1
},
"brand_subdomains": [
{
"domain": "<string>",
"citations": 1
}
],
"top_domains": [
{
"root_domain": "<string>",
"citations": 1,
"share_ratio": 0.5,
"is_brand_domain": true,
"domain_type": "you"
}
],
"platforms": [
{
"platform_code": "<string>",
"platform_name": "<string>",
"citations": 1,
"share_ratio": 0.5
}
]
},
"prev_ready": true,
"coverage": {
"ready_dates": [
"<string>"
],
"missing_dates": [
"<string>"
],
"as_of_at": "2023-11-07T05:31:56Z"
},
"invalid_filter": "competitors",
"totals": {
"root_domains": 1,
"citations": 1
},
"you": {
"root_domains": [
"<string>"
],
"citations": 1,
"share_ratio": 0.5,
"rank": 1
},
"movers": {
"top": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
],
"new": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
],
"up": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
],
"down": [
{
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
}
]
},
"entered_top20": [
"<string>"
],
"biggest_drop": {
"root_domain": "<string>",
"citations": 1,
"prev_citations": 1,
"citations_change_pct": 123,
"is_new": true
},
"trend": {
"default_granularity": "day",
"business_dates": [
"<string>"
],
"series": [
{
"root_domain": "<string>",
"is_you": true,
"values": [
1
]
}
],
"first_date": "<string>"
},
"citations_by_type": {
"you": 1,
"competitor": 1,
"other": 1,
"total": 1
}
},
"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
API key from Settings → Developer → API keys (prefix geom_). Each key is bound to one brand.
Body
application/json
Rolling window of closed business days.
Available options:
7d, 30d, 90d AI platform, or "all".
Available options:
all, chatgpt, perplexity, gemini, google_ai, copilot, google_ai_overview Restrict to these topic ids (1–50). With a filter, stats is null and filtered is true.
Required array length:
1 - 50 elementsRequired string length:
1 - 64Response
The citations report. data follows CitationsReport when meta.schema_conformant is true.