API overview
Read your Opttab workspace's prompts, AI answers, competitors and visibility metrics from your own tools with the read-only Opttab API.
{
"items": [
{
"id": "33333333-3333-4333-8333-333333333333",
"text": "What is the best running shoe for daily training?",
"topicId": "22222222-2222-4222-8222-222222222222",
"topicName": "Running shoes",
"isActive": true,
"cadence": "daily",
"visibility": 42,
"country": "US",
"language": "en",
"targetPlatforms": ["chatgpt", "perplexity"],
"tags": [{ "name": "Running", "subTags": ["Daily"] }],
"lastRunAt": "2026-10-18T12:00:00.000Z"
}
],
"page": 1,
"pageSize": 20,
"totalCount": 1
}
The Opttab API lets you pull your AI visibility data into your own reports, dashboards and data warehouse. It is a REST API that returns JSON.
What you can do with it
- Read, never write. Every route is a
GET. An API key cannot create, change or delete anything in Opttab. - One workspace per key. Each key reads the one workspace you chose when you created it. The workspace never appears in the URL.
- Pick what a key can see. Scopes limit a key to workspace info, prompts and answers, or metrics.
| Scope | What it reads | Routes |
|---|---|---|
v2:org | Workspace info and competitors | GET /v1/external/workspace, GET /v1/external/competitors |
v2:prompts | Prompts, AI answers, cited sources and topics | GET /v1/external/prompts, GET /v1/external/prompts/{promptId}, GET /v1/external/prompts/{promptId}/responses, GET /v1/external/responses/{responseId}/sources, GET /v1/external/topics |
v2:metrics | Visibility, sentiment, share of voice and citation scores | GET /v1/external/metrics/summary, GET /v1/external/metrics/kpis |
How it works
Quick start
Create a key
Go to Settings › API and click Create API Key. Give it a Key Name, choose the Workspace, and tick the scope v2:prompts (Access prompts and their AI responses). Click Create API Key.
Copy the secret
On Copy your API key, click Copy key and store the secret somewhere safe, such as a secrets manager. It starts with opt_live_ and is shown only once.
Make your first call
Send the key as a bearer token:
curl "https://api.opttab.com/v1/external/prompts?page=1&pageSize=20" \
-H "Authorization: Bearer opt_live_xxxxxxxx"
const response = await fetch(
'https://api.opttab.com/v1/external/prompts?page=1&pageSize=20',
{ headers: { Authorization: `Bearer ${process.env.OPTTAB_API_KEY}` } }
);
const page = await response.json();
import os
import requests
response = requests.get(
"https://api.opttab.com/v1/external/prompts",
params={"page": 1, "pageSize": 20},
headers={"Authorization": f"Bearer {os.environ['OPTTAB_API_KEY']}"},
)
page = response.json()
Read the JSON
You get one page of prompts, plus the paging fields:
Use a prompt's id to fetch its AI answers with GET /v1/external/prompts/{promptId}/responses, then an answer's id to fetch the pages it cited with GET /v1/external/responses/{responseId}/sources.
Good to know
- Rate limit: 60 requests per 60 seconds per key. See Authentication, limits and errors.
- Paging: list routes take
page(default 1) andpageSize(default 20, maximum 100). - Periods: metrics routes take
period:1d,7d,30d,3m,6mor1y. Omitted, it is the last seven days. - AI engines appear as ids:
chatgpt,grok,gemini,claude,perplexity,deepseek,mistral,google_ai_mode,copilot,google_ai_overview.