Limits and pagination
60 requests per minute and 10,000 per day per key, with an account ceiling of 30,000 per day. Revoking a key does not restore consumed quota. PDFs: 10 per minute and 50 per day per account, 20 per day per key and one at a time per account. Authentication failures are limited by IP; valid keys used in the last seven days continue to work even when that limit is reached. IPv6 addresses share a /64 quota and mapped IPv4 addresses share their original IPv4 quota. Check X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. On a 429, wait for the seconds in Retry-After.
For lists, use page (starting at 1) and limit (1–100; default 50). The offset (page − 1) × limit cannot exceed 10,000; exceeding it returns 400 invalid_query. pagination.has_more indicates another page. Use lang=es or lang=en; the default is es. Missing older translations fall back to the available text. Questions and responses retain their original language. Responses are not cached. Examples use fictional data.
Each response indicates whether your brand appears. Responses counted per question and provider.
Escape third-party text when displaying it: AI responses, sources and competitor names. sources contains only valid http(s) URLs.
Available resources
Account businesses
GET /api/v1/workspaces
curl 'https://surfeo.ai/api/v1/workspaces?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example Clinic",
"url": "https://example.com",
"sector": "health",
"city": "Granada",
"region": "Andalucía",
"country": "ES",
"language": "en",
"plan": "growth",
"created_at": "2026-10-01T10:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
Business profile and latest score
GET /api/v1/workspaces/{id}
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example Clinic",
"url": "https://example.com",
"sector": "health",
"city": "Granada",
"region": "Andalucía",
"country": "ES",
"language": "en",
"plan": "growth",
"created_at": "2026-10-01T10:00:00Z",
"latest_score": {
"audit_id": "22222222-2222-4222-8222-222222222222",
"score": 72,
"label": "Dominant",
"created_at": "2026-10-01T10:00:00Z",
"reliable": true
}
}
}
Score history. from and to accept ISO 8601 dates, with both bounds included. A date without a time covers the full UTC day.
GET /api/v1/workspaces/{id}/scores
Filters: from, to
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/scores?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"audit_id": "22222222-2222-4222-8222-222222222222",
"score": 72,
"label": "Dominant",
"created_at": "2026-10-01T10:00:00Z",
"reliable": true
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
Business questions
GET /api/v1/workspaces/{id}/questions
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/questions?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"id": "33333333-3333-4333-8333-333333333333",
"text": "Which clinics are in Granada?",
"language": "en",
"active": true,
"custom": false
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
Question mention history
GET /api/v1/workspaces/{id}/questions/{questionId}/history
Filters: audit_id, provider, mentioned
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/questions/33333333-3333-4333-8333-333333333333/history?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"audit_id": "22222222-2222-4222-8222-222222222222",
"question_id": "33333333-3333-4333-8333-333333333333",
"provider": "chatgpt",
"mentioned": true,
"position": 2,
"sentiment": "positive",
"created_at": "2026-10-01T10:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
AI responses from the latest completed audit by default. Use audit_id for another completed audit, and provider or mentioned=true|false to filter.
GET /api/v1/workspaces/{id}/responses
Filters: audit_id, provider, mentioned
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/responses?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"question_id": "33333333-3333-4333-8333-333333333333",
"question": "Which clinics are in Granada?",
"provider": "chatgpt",
"mentioned": true,
"position": 2,
"sentiment": "positive",
"competitors": [
"Neighbor Clinic"
],
"sources": [
"https://example.com/"
],
"response": "Example Clinic provides care in Granada.",
"created_at": "2026-10-01T10:00:00Z",
"audit_id": "22222222-2222-4222-8222-222222222222"
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
Competitors and your brand in the latest completed audit
GET /api/v1/workspaces/{id}/competitors
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/competitors?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": {
"audit_id": "22222222-2222-4222-8222-222222222222",
"brand": {
"name": "Example Clinic",
"url": "https://example.com",
"mentions": 6,
"mention_rate": 0.75
},
"competitors": [
{
"name": "Neighbor Clinic",
"url": "https://example.org",
"main": true,
"mentions": 4,
"mention_rate": 0.5
}
]
},
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
Recommendations. Filter by status=pending|completed|verified.
GET /api/v1/workspaces/{id}/recommendations
Filters: status
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/recommendations?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"id": "33333333-3333-4333-8333-333333333333",
"title": "Complete the contact page",
"description": "Publish your contact details.",
"instructions": "Add your address and opening hours.",
"category": "content",
"priority": 1,
"difficulty": "easy",
"estimated_impact": "medium",
"target_page": "https://example.com/contact",
"completed": true,
"verified": true,
"created_at": "2026-10-01T10:00:00Z",
"completed_at": "2026-10-01T10:00:00Z",
"verified_at": "2026-10-01T10:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
Completed audits and report links
GET /api/v1/workspaces/{id}/audits
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"id": "22222222-2222-4222-8222-222222222222",
"completed_at": "2026-10-01T10:00:00Z",
"score": 72,
"summary": "Your visibility has improved.",
"quick_win": {
"action": "Publish your opening hours on your website.",
"impact": "medium",
"effort": "easy"
},
"report_url": "/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits/22222222-2222-4222-8222-222222222222/report.pdf?lang=en"
}
],
"pagination": {
"page": 1,
"limit": 50,
"has_more": false
}
}
PDF report for a completed audit
GET /api/v1/workspaces/{id}/audits/{auditId}/report.pdf
curl 'https://surfeo.ai/api/v1/workspaces/11111111-1111-4111-8111-111111111111/audits/22222222-2222-4222-8222-222222222222/report.pdf?lang=en' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-o report.pdf
The response is an application/pdf file. Save the download as report.pdf.
Business data (legacy)
GET /api/v1/data
Legacy. Requires a key for a specific business and a paid plan or active trial, with payments up to date. Account keys receive 403 workspace_key_required.
curl 'https://surfeo.ai/api/v1/data' -H 'Authorization: Bearer YOUR_BUSINESS_API_KEY'
{
"data": {
"workspace": {
"id": "11111111-1111-4111-8111-111111111111",
"name": "Example Clinic",
"url": "https://example.com",
"plan": "growth",
"sector": "health",
"city": "Granada",
"region": "Andalucía",
"country": "ES"
},
"scores": [
{
"overall_score": 72,
"label": "good",
"created_at": "2026-10-01T10:00:00Z"
}
],
"recommendations": [
{
"title": "Complete the contact page",
"title_en": "Complete the contact page",
"description": "Publish your contact details.",
"description_en": "Publish your contact details.",
"category": "content",
"priority": 1,
"difficulty": "easy"
}
],
"last_audit": {
"status": "completed",
"completed_at": "2026-10-01T10:00:00Z"
}
}
}
AI overview (legacy)
GET /api/v1/providers
Legacy. Requires a key for a specific business and a paid plan or active trial, with payments up to date. Account keys receive 403 workspace_key_required.
curl 'https://surfeo.ai/api/v1/providers' -H 'Authorization: Bearer YOUR_BUSINESS_API_KEY'
{
"data": {
"providers": [
{
"provider": "chatgpt",
"label": "ChatGPT",
"locked": false,
"mention_rate": 75,
"avg_position": 2,
"dominant_sentiment": "positive",
"total_responses": 4
}
]
}
}
Request a free diagnostic (public)
POST /api/v1/quick-audit
Public, no key required. Diagnostics are subject to IP, domain and daily capacity limits. Status requests have a separate IP limit. Reaching a limit returns 429; try again later.
curl 'https://surfeo.ai/api/v1/quick-audit' -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'
{
"data": {
"audit_id": "22222222-2222-4222-8222-222222222222",
"status": "pending",
"status_url": "/api/v1/quick-audit/22222222-2222-4222-8222-222222222222/status"
}
}
Free diagnostic status (public)
GET /api/v1/quick-audit/{id}/status
Public, no key required. Diagnostics are subject to IP, domain and daily capacity limits. Status requests have a separate IP limit. Reaching a limit returns 429; try again later.
curl 'https://surfeo.ai/api/v1/quick-audit/11111111-1111-4111-8111-111111111111/status'
{
"data": {
"status": "pending",
"score": null,
"label": null,
"providers": null,
"findings_preview": null,
"sector_benchmark": null,
"signup_url": null
}
}