Daily visibility metrics by platform / total / topic

curl --request POST \
  --url https://app.geoly.ai/api/v1/reports/analytics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_utc_date": "<string>",
  "end_utc_date": "<string>"
}
'

import requests

url = "https://app.geoly.ai/api/v1/reports/analytics"

payload = {
    "start_utc_date": "<string>",
    "end_utc_date": "<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({start_utc_date: '<string>', end_utc_date: '<string>'})
};

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

{
  "data": {
    "status": "ready",
    "reason": null,
    "sentiment_not_ready_reason": "<string>",
    "breakdown": "platform",
    "window": {
      "start_utc_date": "<string>",
      "end_utc_date": "<string>",
      "days": 1,
      "days_with_data": 1,
      "current": {
        "start_utc_date": "<string>",
        "end_utc_date": "<string>",
        "days": 1,
        "days_with_data": 1
      },
      "previous": {
        "start_utc_date": "<string>",
        "end_utc_date": "<string>",
        "days": 1,
        "days_with_data": 1
      }
    },
    "platform": "<string>",
    "scope": {
      "active": true,
      "topic_ids": [
        "<string>"
      ],
      "country": "<string>",
      "collapsed": true
    },
    "rows": [
      {
        "utc_date": "<string>",
        "business_date": "<string>",
        "platform_code": "<string>",
        "platform_name": "<string>",
        "topic_id": "<string>",
        "topic_name": "<string>",
        "completed_records": 1,
        "mentioned_records": 1,
        "mention_count": 1,
        "domain_cited_records": 1,
        "visibility_score": 50,
        "mention_rate_pct": 50,
        "domain_citation_rate_pct": 50,
        "sentiment": {
          "positive": 1,
          "neutral": 1,
          "negative": 1,
          "mixed": 1,
          "unknown": 1,
          "scored_records": 1,
          "avg_polarity": 0
        },
        "previous": {
          "utc_date": "<string>",
          "business_date": "<string>",
          "completed_records": 1,
          "mentioned_records": 1,
          "mention_count": 1,
          "domain_cited_records": 1,
          "visibility_score": 50,
          "mention_rate_pct": 50,
          "domain_citation_rate_pct": 50,
          "sentiment": {
            "positive": 1,
            "neutral": 1,
            "negative": 1,
            "mixed": 1,
            "unknown": 1,
            "scored_records": 1,
            "avg_polarity": 0
          }
        },
        "delta": {
          "completed_records": 123,
          "mentioned_records": 123,
          "mention_count": 123,
          "domain_cited_records": 123,
          "visibility_score": 123,
          "mention_rate_pp": 123,
          "domain_citation_rate_pp": 123,
          "sentiment": {
            "positive": 123,
            "neutral": 123,
            "negative": 123,
            "mixed": 123,
            "unknown": 123,
            "scored_records": 123,
            "avg_polarity": 123
          }
        }
      }
    ],
    "totals": [
      {
        "utc_date": "<string>",
        "business_date": "<string>",
        "platform_code": "<string>",
        "platform_name": "<string>",
        "topic_id": "<string>",
        "topic_name": "<string>",
        "completed_records": 1,
        "mentioned_records": 1,
        "mention_count": 1,
        "domain_cited_records": 1,
        "visibility_score": 50,
        "mention_rate_pct": 50,
        "domain_citation_rate_pct": 50,
        "sentiment": {
          "positive": 1,
          "neutral": 1,
          "negative": 1,
          "mixed": 1,
          "unknown": 1,
          "scored_records": 1,
          "avg_polarity": 0
        },
        "previous": {
          "utc_date": "<string>",
          "business_date": "<string>",
          "completed_records": 1,
          "mentioned_records": 1,
          "mention_count": 1,
          "domain_cited_records": 1,
          "visibility_score": 50,
          "mention_rate_pct": 50,
          "domain_citation_rate_pct": 50,
          "sentiment": {
            "positive": 1,
            "neutral": 1,
            "negative": 1,
            "mixed": 1,
            "unknown": 1,
            "scored_records": 1,
            "avg_polarity": 0
          }
        },
        "delta": {
          "completed_records": 123,
          "mentioned_records": 123,
          "mention_count": 123,
          "domain_cited_records": 123,
          "visibility_score": 123,
          "mention_rate_pp": 123,
          "domain_citation_rate_pp": 123,
          "sentiment": {
            "positive": 123,
            "neutral": 123,
            "negative": 123,
            "mixed": 123,
            "unknown": 123,
            "scored_records": 123,
            "avg_polarity": 123
          }
        }
      }
    ],
    "capped": {
      "total_rows": 1,
      "shown_rows": 1,
      "shown_from_utc_date": "<string>",
      "total_groups": 1,
      "shown_groups": 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"
    }
  }
}

报表

每日可见度指标

Fixed columns per day (completed / mentioned answers, mention and citation rates, visibility score, sentiment buckets), optionally with the previous equal-length window. Rows carry both utc_date and business_date. Very long windows with breakdown=platform or topic may be capped (data.capped is then non-null and says what was kept). 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

analytics

Daily visibility metrics by platform / total / topic

curl --request POST \
  --url https://app.geoly.ai/api/v1/reports/analytics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_utc_date": "<string>",
  "end_utc_date": "<string>"
}
'

import requests

url = "https://app.geoly.ai/api/v1/reports/analytics"

payload = {
    "start_utc_date": "<string>",
    "end_utc_date": "<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({start_utc_date: '<string>', end_utc_date: '<string>'})
};

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

{
  "data": {
    "status": "ready",
    "reason": null,
    "sentiment_not_ready_reason": "<string>",
    "breakdown": "platform",
    "window": {
      "start_utc_date": "<string>",
      "end_utc_date": "<string>",
      "days": 1,
      "days_with_data": 1,
      "current": {
        "start_utc_date": "<string>",
        "end_utc_date": "<string>",
        "days": 1,
        "days_with_data": 1
      },
      "previous": {
        "start_utc_date": "<string>",
        "end_utc_date": "<string>",
        "days": 1,
        "days_with_data": 1
      }
    },
    "platform": "<string>",
    "scope": {
      "active": true,
      "topic_ids": [
        "<string>"
      ],
      "country": "<string>",
      "collapsed": true
    },
    "rows": [
      {
        "utc_date": "<string>",
        "business_date": "<string>",
        "platform_code": "<string>",
        "platform_name": "<string>",
        "topic_id": "<string>",
        "topic_name": "<string>",
        "completed_records": 1,
        "mentioned_records": 1,
        "mention_count": 1,
        "domain_cited_records": 1,
        "visibility_score": 50,
        "mention_rate_pct": 50,
        "domain_citation_rate_pct": 50,
        "sentiment": {
          "positive": 1,
          "neutral": 1,
          "negative": 1,
          "mixed": 1,
          "unknown": 1,
          "scored_records": 1,
          "avg_polarity": 0
        },
        "previous": {
          "utc_date": "<string>",
          "business_date": "<string>",
          "completed_records": 1,
          "mentioned_records": 1,
          "mention_count": 1,
          "domain_cited_records": 1,
          "visibility_score": 50,
          "mention_rate_pct": 50,
          "domain_citation_rate_pct": 50,
          "sentiment": {
            "positive": 1,
            "neutral": 1,
            "negative": 1,
            "mixed": 1,
            "unknown": 1,
            "scored_records": 1,
            "avg_polarity": 0
          }
        },
        "delta": {
          "completed_records": 123,
          "mentioned_records": 123,
          "mention_count": 123,
          "domain_cited_records": 123,
          "visibility_score": 123,
          "mention_rate_pp": 123,
          "domain_citation_rate_pp": 123,
          "sentiment": {
            "positive": 123,
            "neutral": 123,
            "negative": 123,
            "mixed": 123,
            "unknown": 123,
            "scored_records": 123,
            "avg_polarity": 123
          }
        }
      }
    ],
    "totals": [
      {
        "utc_date": "<string>",
        "business_date": "<string>",
        "platform_code": "<string>",
        "platform_name": "<string>",
        "topic_id": "<string>",
        "topic_name": "<string>",
        "completed_records": 1,
        "mentioned_records": 1,
        "mention_count": 1,
        "domain_cited_records": 1,
        "visibility_score": 50,
        "mention_rate_pct": 50,
        "domain_citation_rate_pct": 50,
        "sentiment": {
          "positive": 1,
          "neutral": 1,
          "negative": 1,
          "mixed": 1,
          "unknown": 1,
          "scored_records": 1,
          "avg_polarity": 0
        },
        "previous": {
          "utc_date": "<string>",
          "business_date": "<string>",
          "completed_records": 1,
          "mentioned_records": 1,
          "mention_count": 1,
          "domain_cited_records": 1,
          "visibility_score": 50,
          "mention_rate_pct": 50,
          "domain_citation_rate_pct": 50,
          "sentiment": {
            "positive": 1,
            "neutral": 1,
            "negative": 1,
            "mixed": 1,
            "unknown": 1,
            "scored_records": 1,
            "avg_polarity": 0
          }
        },
        "delta": {
          "completed_records": 123,
          "mentioned_records": 123,
          "mention_count": 123,
          "domain_cited_records": 123,
          "visibility_score": 123,
          "mention_rate_pp": 123,
          "domain_citation_rate_pp": 123,
          "sentiment": {
            "positive": 123,
            "neutral": 123,
            "negative": 123,
            "mixed": 123,
            "unknown": 123,
            "scored_records": 123,
            "avg_polarity": 123
          }
        }
      }
    ],
    "capped": {
      "total_rows": 1,
      "shown_rows": 1,
      "shown_from_utc_date": "<string>",
      "total_groups": 1,
      "shown_groups": 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"
    }
  }
}

授权

Authorization

string

header

必填

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

请求体

application/json

start_utc_date

string

必填

First UTC record-day key (YYYY-MM-DD; = business day − 1). Passed to the report as start_date.

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

end_utc_date

string

必填

Last UTC record-day key, inclusive (YYYY-MM-DD). Passed to the report as end_date. At most 366 days.

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

breakdown

enum<string>

默认值:platform

One row per day × platform / per day / per day × topic.

可用选项:

platform,

total,

topic

platform

enum<string>

默认值:all

AI platform, or "all".

可用选项:

all,

chatgpt,

gemini,

perplexity,

google_ai,

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

compare_previous

boolean

默认值:false

Also return the previous equal-length window (previous / delta on every row and total).

响应

The analytics report. data follows AnalyticsReport when meta.schema_conformant is true.

data

object

必填

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

Option 1
Option 2

Show child attributes

开始使用

账号

目录

监测记录

报表

每日可见度指标

授权

请求体

响应