Octolens API Skill

When to use this skill

Use this skill when the user needs to:

Fetch brand mentions from social media and other platforms
Filter mentions by source (Twitter, Reddit, GitHub, LinkedIn, YouTube, HackerNews, DevTO, StackOverflow, Bluesky, newsletters, podcasts)
Analyze sentiment (positive, neutral, negative)
Filter by author follower count or engagement
Search for specific keywords or tags
Query mentions by date range
List available keywords or saved views
Apply complex filtering logic with AND/OR conditions

API Authentication

The Octolens API requires a Bearer token for authentication. The user should provide their API key, which you'll use in the

Authorization

header:

Authorization: Bearer YOUR_API_KEY

Important: Always ask the user for their API key before making any API calls. Store it in a variable for subsequent requests.

Base URL

All API endpoints use the base URL:

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

Rate Limits

Limit: 500 requests per hour
Check headers:
```
X-RateLimit-*
```
headers indicate current usage

Available Endpoints

1. POST /mentions

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

Key Parameters:

```
limit
```
(number, 1-100): Maximum results to return (default: 20)
```
cursor
```
(string): Pagination cursor from previous response
```
includeAll
```
(boolean): Include low-relevance posts (default: false)
```
view
```
(number): View ID to use for filtering
```
filters
```
(object): Filter criteria (see filtering section)

Example Response:

{
  "data": [
    {
      "id": "abc123",
      "url": "https://twitter.com/user/status/123",
      "body": "Just discovered @YourProduct - this is exactly what I needed!",
      "source": "twitter",
      "timestamp": "2024-01-15T10:30:00Z",
      "author": "user123",
      "authorName": "John Doe",
      "authorFollowers": 5420,
      "relevance": "relevant",
      "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 the organization.

Example Response:

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

3. GET /views

List all saved views (pre-configured filters).

Example Response:

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

Filtering Mentions

The

/mentions

endpoint supports powerful filtering with two modes:

Simple Mode (Implicit AND)

Put fields directly in filters. All conditions are ANDed together.

{
  "filters": {
    "source": ["twitter", "linkedin"],
    "sentiment": ["positive"],
    "minXFollowers": 1000
  }
}

→

source IN (twitter, linkedin) AND sentiment = positive AND followers ≥ 1000

Exclusions

Prefix any array field with ! to exclude values:

{
  "filters": {
    "source": ["twitter"],
    "!keyword": [5, 6]
  }
}

→

source = twitter AND keyword NOT IN (5, 6)

Advanced Mode (AND/OR Groups)

Use

operator

and

groups

for complex logic:

{
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "OR",
        "conditions": [
          { "source": ["twitter"] },
          { "source": ["linkedin"] }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "sentiment": ["positive"] },
          { "!tag": ["spam"] }
        ]
      }
    ]
  }
}

→

(source = twitter OR source = linkedin) AND (sentiment = positive AND tag ≠ spam)

Available Filter Fields

Field	Type	Description
`source`	string[]	Platforms: twitter, reddit, github, linkedin, youtube, hackernews, devto, stackoverflow, bluesky, newsletter, podcast
`sentiment`	string[]	Values: positive, neutral, negative
`keyword`	string[]	Keyword IDs (get from /keywords endpoint)
`language`	string[]	ISO 639-1 codes: en, es, fr, de, pt, it, nl, ja, ko, zh
`tag`	string[]	Tag names
`bookmarked`	boolean	Filter bookmarked (true) or non-bookmarked (false) posts
`engaged`	boolean	Filter engaged (true) or non-engaged (false) posts
`minXFollowers`	number	Minimum Twitter follower count
`maxXFollowers`	number	Maximum Twitter follower count
`startDate`	string	ISO 8601 format (e.g., "2024-01-15T00:00:00Z")
`endDate`	string	ISO 8601 format

Using the Bundled Scripts

This skill includes helper scripts for common operations. Use them to quickly interact with the API:

Fetch Mentions

node scripts/fetch-mentions.js YOUR_API_KEY [limit] [includeAll]

List Keywords

node scripts/list-keywords.js YOUR_API_KEY

List Views

node scripts/list-views.js YOUR_API_KEY

Custom Filter Query

node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"]}' [limit]

Advanced Query

node scripts/advanced-query.js YOUR_API_KEY [limit]

Best Practices

Always ask for the API key before making requests
Use views when possible to leverage pre-configured filters
Start with simple filters and add complexity as needed
Check rate limits in response headers (
```
X-RateLimit-*
```
)
Use pagination with cursor for large result sets
Dates must be ISO 8601 format (e.g., "2024-01-15T00:00:00Z")
Get keyword IDs from
```
/keywords
```
endpoint before filtering by keyword
Use exclusions (!) to filter out unwanted content
Combine includeAll=false with relevance filtering for quality results

Common Use Cases

Find positive Twitter mentions with high followers

{
  "limit": 20,
  "filters": {
    "source": ["twitter"],
    "sentiment": ["positive"],
    "minXFollowers": 1000
  }
}

Exclude spam and get Reddit + GitHub mentions

{
  "limit": 50,
  "filters": {
    "source": ["reddit", "github"],
    "!tag": ["spam", "irrelevant"]
  }
}

Complex query: (Twitter OR LinkedIn) AND positive sentiment, last 7 days

{
  "limit": 30,
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "OR",
        "conditions": [
          { "source": ["twitter"] },
          { "source": ["linkedin"] }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "sentiment": ["positive"] },
          { "startDate": "2024-01-20T00:00:00Z" }
        ]
      }
    ]
  }
}

Error Handling

Status	Error	Description
401	unauthorized	Missing or invalid API key
403	forbidden	Valid key but no permission
404	not_found	Resource (e.g., view ID) not found
429	rate_limit_exceeded	Too many requests
400	invalid_request	Malformed request body
500	internal_error	Server error, retry later

Step-by-Step Workflow

When a user asks to query Octolens data:

Ask for API key if not already provided
Understand the request: What are they looking for?
Determine filters needed: Source, sentiment, date range, etc.
Check if a view applies: List views first if user mentions saved filters
Build the query: Use simple mode first, advanced mode for complex logic
Execute the request: Use bundled Node.js scripts or fetch API directly
Parse results: Extract key information (author, body, sentiment, source)
Handle pagination: If more results needed, use cursor from response
Present findings: Summarize insights, highlight patterns

Examples

Example 1: Simple Query

User: "Show me positive mentions from Twitter in the last 7 days"

Action (using bundled script):

node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"], "startDate": "2024-01-20T00:00:00Z"}'

Alternative (using fetch API directly):

const response = await fetch('https://app.octolens.com/api/v1/mentions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    limit: 20,
    filters: {
      source: ['twitter'],
      sentiment: ['positive'],
      startDate: '2024-01-20T00:00:00Z',
    },
  }),
});
const data = await response.json();

Example 2: Advanced Query

User: "Find mentions from Reddit or GitHub, exclude spam tag, with positive or neutral sentiment"

Action (using bundled script):

node scripts/query-mentions.js YOUR_API_KEY '{"operator": "AND", "groups": [{"operator": "OR", "conditions": [{"source": ["reddit"]}, {"source": ["github"]}]}, {"operator": "OR", "conditions": [{"sentiment": ["positive"]}, {"sentiment": ["neutral"]}]}, {"operator": "AND", "conditions": [{"!tag": ["spam"]}]}]}'

Alternative (using fetch API directly):

const response = await fetch('https://app.octolens.com/api/v1/mentions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    limit: 30,
    filters: {
      operator: 'AND',
      groups: [
        {
          operator: 'OR',
          conditions: [
            { source: ['reddit'] },
            { source: ['github'] },
          ],
        },
        {
          operator: 'OR',
          conditions: [
            { sentiment: ['positive'] },
            { sentiment: ['neutral'] },
          ],
        },
        {
          operator: 'AND',
          conditions: [
            { '!tag': ['spam'] },
          ],
        },
      ],
    },
  }),
});
const data = await response.json();

Example 3: Get Keywords First

User: "Show mentions for our main product keyword"

Actions:

First, list keywords:

node scripts/list-keywords.js YOUR_API_KEY

Then query mentions with the keyword ID:

node scripts/query-mentions.js YOUR_API_KEY '{"keyword": [1]}'

Tips for Agents

Use bundled scripts: The Node.js scripts handle JSON parsing automatically
Cache keywords: After fetching keywords once, remember them for the session
Explain filters: When using complex filters, explain the logic to the user
Show examples: When users are unsure, show example filter structures
Paginate wisely: Ask if user wants more results before fetching next page
Summarize insights: Don't just dump data, provide analysis (sentiment trends, top authors, platform distribution)

Octolens

AI Skill Market Insights

Be Part of the 2,702+ Developer Community

Octolens API Skill

When to use this skill

API Authentication

Base URL

Rate Limits

Available Endpoints

1. POST /mentions

2. GET /keywords

3. GET /views

Filtering Mentions

Simple Mode (Implicit AND)

Exclusions

Advanced Mode (AND/OR Groups)

Available Filter Fields

Using the Bundled Scripts

Fetch Mentions

List Keywords

List Views

Custom Filter Query

Advanced Query

Best Practices

Common Use Cases

Find positive Twitter mentions with high followers

Exclude spam and get Reddit + GitHub mentions

Complex query: (Twitter OR LinkedIn) AND positive sentiment, last 7 days

Error Handling

Step-by-Step Workflow

Examples

Example 1: Simple Query

Example 2: Advanced Query

Example 3: Get Keywords First

Tips for Agents

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company