Octolens

Octolens API Skill

When to use this skill

Use this skill when the user needs to:

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

Available Endpoints

1. POST /mentions

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

Key Parameters:

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
  }
}

Exclusions

Prefix any array field with ! to exclude values:

{
  "filters": {
    "source": ["twitter"],
    "!keyword": [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"] }
        ]
      }
    ]
  }
}

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

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

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

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

Example 1: Simple Query

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

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

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]}'

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