GoGetCited API
Read your projects, prompts, AI answers and visibility metrics from your own tools, and add or pause prompts. The API is part of plans with API access.
Authentication
Workspace owners and admins create API keys in Settings → API. A key is shown once; keep it secret, like a password. Send it with every request:
curl https://gogetcited.com/api/v1/projects \ -H "Authorization: Bearer bv_your_key"
A key reads, or reads and writes. It stops working when it's revoked, and when the person who created it leaves the workspace or is no longer an owner or admin.
Limits and errors
Each key can make 60 requests a minute. Every response says how many are left in X-RateLimit-Remaining; past the limit you get 429 with a Retry-After header. Errors come as {"error": {"code": "…", "message": "…"}}, and the message says what to change.
Dates and paging
Days are YYYY-MM-DD in the project's time zone; periods default to the last 30 days and go up to a year. Lists come newest first, up to limit items (50 by default, 100 at most); pass nextCursor as cursor for the next page.
The full description is at /api/v1/openapi.json (OpenAPI 3.1), for code generators and API clients.
Endpoints
get/projects
List projects
get/projects/{project}/prompts
List prompts
| Parameter | Type | Description |
|---|---|---|
| project*path | string | The project's id or slug. |
| statusquery | active | paused | completed | all | Only prompts with this status. |
| cursorquery | string | nextCursor from the previous page. |
| limitquery | integer | Items per page, 1–100. |
post/projects/{project}/prompts
Add prompts
Adds up to 25 prompts, checked within minutes and then daily. A prompt the project already has (same text) is skipped and listed under skipped, so retrying is safe.
| Parameter | Type | Description |
|---|---|---|
| project*path | string | The project's id or slug. |
curl -X POST https://gogetcited.com/api/v1/projects/my-project/prompts \
-H "Authorization: Bearer bv_your_key" \
-H "Content-Type: application/json" \
-d '{"prompts": [{"prompt": "best family hotels in Lisbon", "markets": ["us:en"], "topic": "Hotels", "tags": ["family"]}]}'get/projects/{project}/prompts/{prompt}
Get a prompt
| Parameter | Type | Description |
|---|---|---|
| project*path | string | The project's id or slug. |
| prompt*path | string | The prompt's id. |
patch/projects/{project}/prompts/{prompt}
Pause or resume a prompt
| Parameter | Type | Description |
|---|---|---|
| project*path | string | The project's id or slug. |
| prompt*path | string | The prompt's id. |
curl -X PATCH https://gogetcited.com/api/v1/projects/my-project/prompts/PROMPT_ID \
-H "Authorization: Bearer bv_your_key" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'get/projects/{project}/answers
List AI answers
Answers to the project's prompts, newest first, with the tracked brands they name and the pages they cite.
| Parameter | Type | Description |
|---|---|---|
| project*path | string | The project's id or slug. |
| fromquery | string | First day (default: 30 days ago). |
| toquery | string | Last day (default: today). |
| enginequery | google_aio | google_ai_mode | chatgpt | perplexity | gemini | copilot | claude | An AI engine: google_aio (Google AI Overviews), google_ai_mode (Google AI Mode), chatgpt (ChatGPT), perplexity (Perplexity), gemini (Gemini), copilot (Microsoft Copilot), claude (Claude). |
| marketquery | string | A market: country and language, like us:en or be:nl. |
| promptquery | string | Only answers to this prompt. |
| cursorquery | string | nextCursor from the previous page. |
| limitquery | integer | Items per page, 1–100. |
get/projects/{project}/metrics
Get visibility metrics
Per tracked brand: visibility, share of voice, average position and sentiment for the period, the same for the period of equal length before, and a visibility trend.
| Parameter | Type | Description |
|---|---|---|
| project*path | string | The project's id or slug. |
| fromquery | string | First day (default: 30 days ago). |
| toquery | string | Last day (default: today). |
| enginequery | google_aio | google_ai_mode | chatgpt | perplexity | gemini | copilot | claude | An AI engine: google_aio (Google AI Overviews), google_ai_mode (Google AI Mode), chatgpt (ChatGPT), perplexity (Perplexity), gemini (Gemini), copilot (Microsoft Copilot), claude (Claude). |
| marketquery | string | A market: country and language, like us:en or be:nl. |
| topicquery | string | Only prompts of this topic. |
| tagquery | string | Only prompts with this tag. |
| granularityquery | day | week | month | Trend buckets (default: by the period's length). |
Webhooks
Instead of asking the API for news, let GoGetCited tell you: add a webhook in Settings → API, with an HTTPS address and the events you want. Each event is a POST with a JSON body {"type": "…", "timestamp": "…", "data": {…}}. "Send a test" posts a webhook.test event.
run.completed A prompt's check finished
{
"project": {
"id": "…",
"name": "Acme"
},
"prompt": {
"id": "…",
"text": "best family hotels in Lisbon"
},
"markets": [
"us:en",
"gb:en"
],
"engines": [
"google_aio",
"chatgpt"
],
"skipped": {
"chatgpt": [
"gb:en"
]
},
"answers": 3,
"unavailable": 0,
"roundStartedAt": "2026-10-09T06:00:00.000Z"
}skipped lists, per engine, the markets the project's engine settings left out of this check (an engine that runs once a week, or only in some markets). They aren't failures.
alert.fired An alert fired
{
"alert": {
"id": "…",
"kind": "visibility_drop",
"title": "Acme's visibility fell 12 points",
"body": "…",
"url": "https://…"
},
"project": {
"id": "…",
"name": "Acme"
}
}opportunity.created A new action was found
{
"opportunity": {
"id": "…",
"kind": "content_gap",
"group": "owned",
"title": "…",
"url": "https://…"
},
"project": {
"id": "…",
"name": "Acme"
}
}Checking a delivery
Deliveries are signed the Standard Webhooks way, with the secret shown when you added the webhook: headers webhook-id, webhook-timestamp and webhook-signature. Their libraries check it for you, for example in Node.js:
import { Webhook } from "standardwebhooks";
// The secret shown when you added the webhook (whsec_…).
const wh = new Webhook(process.env.GOGETCITED_WEBHOOK_SECRET);
app.post("/webhooks/gogetcited", express.raw({ type: "application/json" }), (req, res) => {
const event = wh.verify(req.body, req.headers); // throws if the signature is wrong or old
// event.type, event.timestamp, event.data
res.sendStatus(204);
});Retries
Answer with a 2xx status within 10 seconds. Anything else is tried again after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours (about two days in all). A webhook that fails without a single success for three days is turned off. The webhook-id stays the same on every try, so you can skip one you already handled.