Prompt table with per-prompt metrics (paginated)
curl --request POST \
--url https://app.geoly.ai/api/v1/reports/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"limit": 20,
"cursor": "<string>",
"search": "<string>",
"sort_order": "desc",
"time_range": "30d",
"start_date": "<string>",
"end_date": "<string>",
"platform": "all",
"topic_ids": [
"<string>"
],
"tags": [
"<string>"
],
"status": "active",
"country": "<string>",
"include_competitors": false
}
'import requests
url = "https://app.geoly.ai/api/v1/reports/prompts"
payload = {
"limit": 20,
"cursor": "<string>",
"search": "<string>",
"sort_order": "desc",
"time_range": "30d",
"start_date": "<string>",
"end_date": "<string>",
"platform": "all",
"topic_ids": ["<string>"],
"tags": ["<string>"],
"status": "active",
"country": "<string>",
"include_competitors": 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({
limit: 20,
cursor: '<string>',
search: '<string>',
sort_order: 'desc',
time_range: '30d',
start_date: '<string>',
end_date: '<string>',
platform: 'all',
topic_ids: ['<string>'],
tags: ['<string>'],
status: 'active',
country: '<string>',
include_competitors: false
})
};
fetch('https://app.geoly.ai/api/v1/reports/prompts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"prompts": [
{
"id": "<string>",
"text": "<string>",
"category": "<string>",
"tags": [
"<string>"
],
"country": "<string>",
"is_active": true,
"topic_id": "<string>",
"topic_name": "<string>",
"archived_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"is_branded": true,
"in_flight_records": 1,
"records": 1,
"citations": 1,
"brand_citation_records": 1,
"platforms": [
{
"platform_code": "<string>",
"position": 123,
"mentions": 123,
"status": "<string>",
"record_date_at": "2023-11-07T05:31:56Z"
}
],
"performance": {
"total_mentions": 1,
"avg_position": 123,
"has_top3": true,
"has_top5": true,
"has_top10": true
},
"geo_metrics": {
"visibility_score": 50,
"mention_rate_pct": 50,
"citation_rate_pct": 50,
"mentioned_records": 1,
"completed_records": 1,
"delta": {
"visibility_score": 123,
"avg_position": 123,
"citation_rate_pp": 123,
"share_pp": 123
},
"delta_insufficient": {
"visibility_score": true
}
},
"competitors_state": "deferred",
"som": {
"share_pct": 50,
"rank": 1,
"total_competitors": 1
},
"competitor_mentions": [
{
"name": "<string>",
"mentioned_records": 1,
"share_pct": 50,
"domain": "<string>"
}
]
}
],
"summary": {
"visibility_score": 50,
"mention_rate_pct": 50,
"citation_rate_pct": 50,
"delta": {
"visibility_score": 123,
"mention_rate_pp": 123,
"citation_rate_pp": 123
},
"delta_insufficient": {
"visibility_score": true,
"mention_rate_pp": true,
"citation_rate_pp": true
}
},
"competitors_included": true,
"country_options": [
"<string>"
]
},
"page": {
"next_cursor": "<string>",
"limit": 123,
"total": 123,
"capped": true
},
"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
Prompts report
The in-app prompts table: per-prompt visibility, mention rate, citation rate, latest record per platform and window-over-window deltas, plus a summary of the whole filtered set. Paginate with cursor until page.next_cursor is null; the same filters and limit must be sent with every page. 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
/
prompts
Prompt table with per-prompt metrics (paginated)
curl --request POST \
--url https://app.geoly.ai/api/v1/reports/prompts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"limit": 20,
"cursor": "<string>",
"search": "<string>",
"sort_order": "desc",
"time_range": "30d",
"start_date": "<string>",
"end_date": "<string>",
"platform": "all",
"topic_ids": [
"<string>"
],
"tags": [
"<string>"
],
"status": "active",
"country": "<string>",
"include_competitors": false
}
'import requests
url = "https://app.geoly.ai/api/v1/reports/prompts"
payload = {
"limit": 20,
"cursor": "<string>",
"search": "<string>",
"sort_order": "desc",
"time_range": "30d",
"start_date": "<string>",
"end_date": "<string>",
"platform": "all",
"topic_ids": ["<string>"],
"tags": ["<string>"],
"status": "active",
"country": "<string>",
"include_competitors": 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({
limit: 20,
cursor: '<string>',
search: '<string>',
sort_order: 'desc',
time_range: '30d',
start_date: '<string>',
end_date: '<string>',
platform: 'all',
topic_ids: ['<string>'],
tags: ['<string>'],
status: 'active',
country: '<string>',
include_competitors: false
})
};
fetch('https://app.geoly.ai/api/v1/reports/prompts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"prompts": [
{
"id": "<string>",
"text": "<string>",
"category": "<string>",
"tags": [
"<string>"
],
"country": "<string>",
"is_active": true,
"topic_id": "<string>",
"topic_name": "<string>",
"archived_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"is_branded": true,
"in_flight_records": 1,
"records": 1,
"citations": 1,
"brand_citation_records": 1,
"platforms": [
{
"platform_code": "<string>",
"position": 123,
"mentions": 123,
"status": "<string>",
"record_date_at": "2023-11-07T05:31:56Z"
}
],
"performance": {
"total_mentions": 1,
"avg_position": 123,
"has_top3": true,
"has_top5": true,
"has_top10": true
},
"geo_metrics": {
"visibility_score": 50,
"mention_rate_pct": 50,
"citation_rate_pct": 50,
"mentioned_records": 1,
"completed_records": 1,
"delta": {
"visibility_score": 123,
"avg_position": 123,
"citation_rate_pp": 123,
"share_pp": 123
},
"delta_insufficient": {
"visibility_score": true
}
},
"competitors_state": "deferred",
"som": {
"share_pct": 50,
"rank": 1,
"total_competitors": 1
},
"competitor_mentions": [
{
"name": "<string>",
"mentioned_records": 1,
"share_pct": 50,
"domain": "<string>"
}
]
}
],
"summary": {
"visibility_score": 50,
"mention_rate_pct": 50,
"citation_rate_pct": 50,
"delta": {
"visibility_score": 123,
"mention_rate_pp": 123,
"citation_rate_pp": 123
},
"delta_insufficient": {
"visibility_score": true,
"mention_rate_pp": true,
"citation_rate_pp": true
}
},
"competitors_included": true,
"country_options": [
"<string>"
]
},
"page": {
"next_cursor": "<string>",
"limit": 123,
"total": 123,
"capped": true
},
"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
Rows per page (1–100).
Required range:
1 <= x <= 100Opaque cursor from page.next_cursor. Must be sent with exactly the same filters and limit.
Required string length:
1 - 512Case-insensitive substring of the prompt text or a tag name.
Required string length:
1 - 200Sort key. Omit for the default: created_at for status=active, archived_at for status=archived.
Available options:
text, visibility, mention_rate, citations, created_at, archived_at Available options:
asc, desc Metrics window. Ignored when start_date + end_date are given.
Available options:
7d, 30d, 90d Start of an exact metrics window; send together with end_date (UTC+8 business day, YYYY-MM-DD).
Pattern:
^\d{4}-\d{2}-\d{2}$End of an exact metrics window; send together with start_date (UTC+8 business day, YYYY-MM-DD).
Pattern:
^\d{4}-\d{2}-\d{2}$AI platform, or "all".
Available options:
all, chatgpt, perplexity, gemini, google_ai, copilot, google_ai_overview Restrict to these topic ids (1–50). "_none" = prompts without a topic.
Required array length:
1 - 50 elementsRequired string length:
1 - 64Restrict to prompts carrying these tags. "_none" = untagged prompts.
Required array length:
1 - 50 elementsRequired string length:
1 - 100Monitored prompts, or archived ones.
Available options:
active, archived ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.
Required string length:
1 - 8Also compute share of voice and competitor mentions per prompt (slower on large brands).
Response
The prompts report. data follows PromptsReport when meta.schema_conformant is true.
The prompts report. null only when meta.schema_conformant is false and the report output could not be mapped.
Show child attributes
Show child attributes
Cursor pagination. next_cursor === null is the only end-of-list signal.
Show child attributes
Show child attributes
Show child attributes
Show child attributes