API Overview

Surva.ai API Overview

The Surva.ai API allows you to programmatically access your keyword data, competitor intelligence, AI visibility metrics, and more. Build custom integrations, automate reporting, or incorporate Surva.ai data into your own applications.

API Access

API access is available on:

• Growth plan - 1,000 requests/month
• Scale plan - 10,000 requests/month
• Enterprise - Custom limits

Getting Your API Key

1. Log in to Surva.ai
2. Go to Settings
3. Click API Keys
4. Click Generate New Key
5. Copy and securely store your key

Your API key grants full access to your account data. Keep it secure and never share it publicly.

Base URL

All API requests use the base URL:

https://api.surva.io/v1

Authentication

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Request Format

The API accepts JSON requests:

Content-Type: application/json

Response Format

All responses return JSON with a consistent structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

Error Responses

Errors return appropriate HTTP status codes:

• 400 - Bad request (invalid parameters)
• 401 - Unauthorized (invalid or missing API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Not found (resource does not exist)
• 429 - Rate limit exceeded
• 500 - Server error

Error response body:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your API rate limit"
  }
}

Rate Limiting

Rate limits are enforced per API key:

• Limits reset monthly on your billing date
• Check remaining quota in response headers
• X-RateLimit-Limit: Your monthly limit
• X-RateLimit-Remaining: Requests remaining

Pagination

List endpoints support pagination:

GET /v1/keywords?page=2&per_page=50

• page - Page number (default: 1)
• per_page - Results per page (default: 20, max: 100)

Available Endpoints

The API provides access to:

• /keywords - List and manage tracked keywords
• /keywords/{id} - Get keyword details
• /keywords/{id}/rankings - Get ranking history
• /competitors - List and manage competitors
• /competitors/{id} - Get competitor details
• /competitors/{id}/ads - Get competitor ads
• /ai-visibility - Get AI visibility data
• /ai-visibility/mentions - Get AI mentions
• /reports - Generate and download reports

SDKs and Libraries

Official SDKs coming soon for:

• JavaScript/Node.js
• Python
• PHP

Support

For API support:

• Email: api-support@surva.io
• API status: status.surva.io