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

1. Always ask for the API key before making requests
2. Use views when possible to leverage pre-configured filters
3. Start with simple filters and add complexity as needed
4. Check rate limits in response headers (X-RateLimit-*)
5. Use pagination with cursor for large result sets
6. Dates must be ISO 8601 format (e.g., "2024-01-15T00:00:00Z")
7. Get keyword IDs from /keywords endpoint before filtering by keyword
8. Use exclusions (!) to filter out unwanted content
9. 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:

1. Ask for API key if not already provided
2. Understand the request: What are they looking for?
3. Determine filters needed: Source, sentiment, date range, etc.
4. Check if a view applies: List views first if user mentions saved filters
5. Build the query: Use simple mode first, advanced mode for complex logic
6. Execute the request: Use bundled Node.js scripts or fetch API directly
7. Parse results: Extract key information (author, body, sentiment, source)
8. Handle pagination: If more results needed, use cursor from response
9. 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:

1. First, list keywords:

node scripts/list-keywords.js YOUR_API_KEY

2. 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)