Skip to main content
With the Octolens API, you can use data from your Octolens workspace to create custom integrations and automations. The Octolens API is available on Scale and Custom plans.

​
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 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/v1

​
Rate Limits

500 requests per hour Check X-RateLimit-* headers for usage

​
Authentication

Bearer token in the Authorization header

​
Example Request

curl -X POST "https://app.octolens.com/api/v1/mentions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

​
Endpoints

​
1. POST /mentions

Fetch mentions matching your keywords with optional filtering. Returns posts sorted by timestamp (newest first).

​
Parameters

NameTypeDescription
viewnumberView ID to use for filtering. View filters are merged with other filters.
limitnumberMaximum number of results to return (1-100). Default: 20
cursorstringPagination cursor from previous response
includeAllbooleanInclude low-relevance posts. When false, only high and medium relevance posts are returned. Default: false

​
Filters (11 options)

You can also check out our AI Filter Wizard to help construct the filter you want.
FilterTypeDescription
filters.sourcestring[]Filter by source platforms. Prefix with ! to exclude. Values: twitter, reddit, github, linkedin, youtube, hackernews, devto, stackoverflow, bluesky, newsletter, podcast
filters.sentimentstring[]Filter by sentiment. Prefix with ! to exclude. Values: positive, neutral, negative
filters.keywordstring[]Filter by specific keyword IDs. Prefix with ! to exclude.
filters.languagestring[]Filter by language codes (ISO 639-1). Prefix with ! to exclude. Values: en, es, fr, de, pt, it, nl, ja, ko, zh
filters.tagstring[]Filter by tags. Prefix with ! to exclude.
filters.bookmarkedbooleanFilter to only bookmarked (true) or non-bookmarked (false) posts.
filters.engagedbooleanFilter to only engaged (true) or non-engaged (false) posts.
filters.minXFollowersnumberMinimum X/Twitter follower count for the author.
filters.maxXFollowersnumberMaximum X/Twitter follower count for the author.
filters.startDatestringOnly return posts from this date onwards (ISO 8601).
filters.endDatestringOnly return posts up to this date (ISO 8601).

​
Request Body

{
  "limit": 20,
  "includeAll": false,
  "filters": {
    "source": ["twitter", "reddit"],
    "sentiment": ["positive", "neutral"],
    "language": ["en"],
    "minXFollowers": 1000,
    "startDate": "2024-01-01T00:00:00Z"
  }
}

​
Response

{
  "data": [
    {
      "id": "abc123",
      "url": "https://twitter.com/user/status/123",
      "title": null,
      "body": "Just discovered @YourProduct - this is exactly what I needed!",
      "source": "twitter",
      "timestamp": "2024-01-15T10:30:00Z",
      "author": "user123",
      "authorName": "John Doe",
      "authorAvatar": "https://...",
      "authorUrl": "https://twitter.com/user123",
      "authorFollowers": 5420,
      "relevance": "relevant",
      "relevanceComment": "Direct mention of product",
      "sentiment": "positive",
      "language": "en",
      "tags": ["feature-request"],
      "keywords": [{ "id": 1, "keyword": "YourProduct" }],
      "bookmarked": false,
      "engaged": false
    }
  ],
  "cursor": "eyJsYXN0SWQiOiAiYWJjMTIzIn0="
}

​
2. GET /keywords

List all keywords configured for your organization. Returns keyword details including platforms and status.

​
Response

{
  "data": [
    {
      "id": 1,
      "keyword": "YourProduct",
      "platforms": ["twitter", "reddit", "github"],
      "color": "#6366f1",
      "paused": false,
      "context": "Our main product name"
    },
    {
      "id": 2,
      "keyword": "CompetitorX",
      "platforms": ["twitter"],
      "color": "#ef4444",
      "paused": false,
      "context": "Main competitor"
    }
  ]
}

​
3. GET /views

List all saved views for your organization. Views contain pre-configured filters that can be used with the mentions endpoint.

​
Response

{
  "data": [
    {
      "id": 1,
      "name": "High Priority",
      "icon": "star",
      "filters": {
        "sentiment": ["positive", "negative"],
        "source": ["twitter"]
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Error Codes

The API uses standard HTTP status codes. Here are the possible error responses.

​
401 unauthorized

Missing or invalid API key. Ensure you include the Authorization header with a valid API key.

​
403 forbidden

API key is valid but doesn’t have permission to access this resource.

​
404 not_found

The requested resource (e.g., view ID) was not found.

​
429 rate_limit_exceeded

Too many requests. Check the X-RateLimit-* headers for limits and reset time.

​
400 invalid_request

The request body is malformed or contains invalid parameters.

​
500 internal_error

An unexpected error occurred. Please try again or contact support.