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:

CODEBLOCK0

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: INLINECODE1

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)
• INLINECODE4 (string): Pagination cursor from previous response
• INLINECODE5 (boolean): Include low-relevance posts (default: false)
• INLINECODE6 (number): View ID to use for filtering
• INLINECODE7 (object): Filter criteria (see filtering section)

Example Response:
CODEBLOCK1

2. GET /keywords

List all keywords configured for the organization.

Example Response:
CODEBLOCK2

3. GET /views

List all saved views (pre-configured filters).

Example Response:
CODEBLOCK3

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.

CODEBLOCK4
→ INLINECODE9

Exclusions

Prefix any array field with ! to exclude values:

CODEBLOCK5
→ INLINECODE10

Advanced Mode (AND/OR Groups)

Use operator and groups for complex logic:

CODEBLOCK6
→ INLINECODE13

Available Filter Fields

Using the Bundled Scripts

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

Fetch Mentions

List Keywords

List Views

Custom Filter Query

Advanced Query

Best Practices

1. 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

Exclude spam and get Reddit + GitHub mentions

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

Error Handling

Step-by-Step Workflow

When a user asks to query Octolens data:

1. 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

Action (using bundled script):
CODEBLOCK15

Alternative (using fetch API directly):
CODEBLOCK16

Example 2: Advanced Query

Action (using bundled script):
CODEBLOCK17

Alternative (using fetch API directly):
CODEBLOCK18

Example 3: Get Keywords First

Actions:

1. 1. First, list keywords:

1. 2. Then query mentions with the keyword ID:

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)