Skip to main content
With the Octolens API, you can use data from your Octolens workspace to create custom integrations and automations. Every action available in the Octolens UI is available here. The Octolens API, MCP server, and webhooks are available on every plan.

​
How to use the Octolens API

​
Create an API Key

In Octolens, navigate to Settings and then the API tab.
  • Click “Add new key”
  • Choose a name for your API key
  • Choose a scope: read, write (implies read), or admin (implies write)
  • Choose an expiration date for your API key from the dropdown
  • Click Create
You can revoke access to an API key at any time by clicking the three dots next to it.

​
Quick Start

​
Base URL

https://app.octolens.com/api/v2

​
Authentication

Bearer token in the Authorization header. Each endpoint documents the scope it requires. 
Authorization: Bearer YOUR_API_KEY

​
Rate Limits

500 requests per hour per organization (across all keys). Every 2xx response returns three headers so clients can pace themselves:
  • X-RateLimit-Limit — the hourly cap (500)
  • X-RateLimit-Remaining — requests left in the current window
  • X-RateLimit-Reset — Unix timestamp (seconds) when the window resets
When the cap is hit, the endpoint returns 429 with a Retry-After header.

​
Example Request

curl -X POST "https://app.octolens.com/api/v2/mentions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'
Building filters by hand can be tedious. Call POST /api/v2/ai/filter-wizard with a natural-language prompt to get a ready-to-paste filters object.

​
Error Handling

All non-2xx responses share the same envelope: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable explanation",
    "status": 400,
    "details": []
  }
}
The code field is a stable ApiErrorCode enum — branch on it programmatically instead of parsing message. VALIDATION_ERROR (400) responses include a details array with per-field issues; inspect details[i].path to pinpoint which input was rejected.

​
Common error codes

HTTPCodeMeaning
400VALIDATION_ERRORRequest body or query is malformed
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENKey lacks the required scope or permission
404NOT_FOUNDResource does not exist
429RATE_LIMITEDHourly cap hit — see Retry-After
500INTERNAL_ERRORUnexpected error — retry or contact support

​
Endpoints

Browse the full endpoint reference in the sidebar, organized by resource: Feeds, Keywords, Mentions, Analytics, Organization, Feedback, AI, Members, and Filters. Each endpoint page includes a live “Try it” playground.