13 KiB
Octolens Filter Reference Guide
This document provides comprehensive documentation on filtering mentions in the Octolens API.
Filter Modes
The Octolens API supports two filtering modes: Simple Mode and Advanced Mode.
Simple Mode (Implicit AND)
In simple mode, all filter conditions are combined with AND logic. Just place fields directly in the filters object.
Structure:
{
"filters": {
"field1": ["value1", "value2"],
"field2": ["value3"],
"field3": value
}
}
Logic: field1 IN (value1, value2) AND field2 = value3 AND field3 = value
Example:
{
"filters": {
"source": ["twitter", "linkedin"],
"sentiment": ["positive"],
"minXFollowers": 1000
}
}
This translates to:
source IN (twitter, linkedin)
AND sentiment = positive
AND follower_count >= 1000
Advanced Mode (AND/OR Groups)
Advanced mode allows you to create complex nested logic with AND/OR operators.
Structure:
{
"filters": {
"operator": "AND",
"groups": [
{
"operator": "OR",
"conditions": [
{ "field1": ["value1"] },
{ "field2": ["value2"] }
]
},
{
"operator": "AND",
"conditions": [
{ "field3": ["value3"] },
{ "field4": ["value4"] }
]
}
]
}
}
Top-level operator: Combines all groups (AND/OR) Group operator: Combines conditions within a group (AND/OR)
Example:
{
"filters": {
"operator": "AND",
"groups": [
{
"operator": "OR",
"conditions": [
{ "source": ["twitter"] },
{ "source": ["linkedin"] }
]
},
{
"operator": "AND",
"conditions": [
{ "sentiment": ["positive"] },
{ "!tag": ["spam"] }
]
}
]
}
}
This translates to:
(source = twitter OR source = linkedin)
AND
(sentiment = positive AND tag != spam)
Exclusion Operator (!)
You can exclude values by prefixing the field name with !. This works in both simple and advanced mode.
Examples:
// Exclude spam and irrelevant tags
{
"filters": {
"!tag": ["spam", "irrelevant"]
}
}
// Get Twitter mentions, excluding keywords 5 and 6
{
"filters": {
"source": ["twitter"],
"!keyword": [5, 6]
}
}
// Everything except negative sentiment
{
"filters": {
"!sentiment": ["negative"]
}
}
Available Filter Fields
source (string[])
Filter by platform/source of the mention.
Values:
twitter- Twitter/X postsreddit- Reddit posts and commentsgithub- GitHub issues, PRs, discussionslinkedin- LinkedIn postsyoutube- YouTube commentshackernews- Hacker News posts and commentsdevto- Dev.to articles and commentsstackoverflow- Stack Overflow questions/answersbluesky- Bluesky postsnewsletter- Newsletter mentionspodcast- Podcast mentions
Examples:
// Social media only
{"source": ["twitter", "linkedin", "bluesky"]}
// Developer platforms
{"source": ["github", "stackoverflow", "hackernews"]}
// Exclude Reddit
{"!source": ["reddit"]}
sentiment (string[])
Filter by sentiment analysis result.
Values:
positive- Positive sentimentneutral- Neutral sentimentnegative- Negative sentiment
Examples:
// Positive only
{"sentiment": ["positive"]}
// Positive or neutral
{"sentiment": ["positive", "neutral"]}
// Exclude negative
{"!sentiment": ["negative"]}
keyword (string[])
Filter by specific keyword IDs. Use the /keywords endpoint to get available keyword IDs.
Type: Array of keyword IDs (numbers as strings or numbers)
Examples:
// Mentions of keyword 1
{"keyword": [1]}
// Mentions of keywords 1, 2, or 3
{"keyword": [1, 2, 3]}
// Exclude keyword 5
{"!keyword": [5]}
Workflow:
- First call
GET /api/v1/keywordsto get keyword IDs - Then use those IDs in your filter
language (string[])
Filter by language of the post (ISO 639-1 codes).
Values:
en- Englishes- Spanishfr- Frenchde- Germanpt- Portugueseit- Italiannl- Dutchja- Japaneseko- Koreanzh- Chinese
Examples:
// English only
{"language": ["en"]}
// English or Spanish
{"language": ["en", "es"]}
// Exclude Japanese
{"!language": ["ja"]}
tag (string[])
Filter by tags applied to mentions.
Type: Array of tag names (strings)
Examples:
// Feature requests only
{"tag": ["feature-request"]}
// High priority or bug tags
{"tag": ["high-priority", "bug"]}
// Exclude spam
{"!tag": ["spam"]}
bookmarked (boolean)
Filter by bookmark status.
Values:
true- Only bookmarked mentionsfalse- Only non-bookmarked mentions
Examples:
// Only bookmarked
{"bookmarked": true}
// Only non-bookmarked
{"bookmarked": false}
engaged (boolean)
Filter by engagement status.
Values:
true- Only engaged mentions (you've replied/interacted)false- Only non-engaged mentions
Examples:
// Only engaged
{"engaged": true}
// Only non-engaged
{"engaged": false}
minXFollowers (number)
Minimum Twitter/X follower count for the author.
Type: Number (integer)
Examples:
// Authors with at least 1000 followers
{"minXFollowers": 1000}
// Influencers (10k+)
{"minXFollowers": 10000}
maxXFollowers (number)
Maximum Twitter/X follower count for the author.
Type: Number (integer)
Examples:
// Small accounts only (under 1000)
{"maxXFollowers": 1000}
// Range: 1000-10000 followers
{"minXFollowers": 1000, "maxXFollowers": 10000}
startDate (string)
Only return mentions from this date onwards.
Format: ISO 8601 timestamp (e.g., 2024-01-15T00:00:00Z)
Examples:
// From January 1, 2024 onwards
{"startDate": "2024-01-01T00:00:00Z"}
// Last 7 days (calculate dynamically)
{"startDate": "2024-01-20T00:00:00Z"}
endDate (string)
Only return mentions up to this date.
Format: ISO 8601 timestamp (e.g., 2024-01-31T23:59:59Z)
Examples:
// Up to January 31, 2024
{"endDate": "2024-01-31T23:59:59Z"}
// Specific date range
{
"startDate": "2024-01-01T00:00:00Z",
"endDate": "2024-01-31T23:59:59Z"
}
Common Filter Patterns
Pattern 1: Platform-Specific Sentiment Analysis
Get positive mentions from Twitter only:
{
"filters": {
"source": ["twitter"],
"sentiment": ["positive"]
}
}
Pattern 2: High-Value Engagement Opportunities
Positive or neutral mentions from high-follower accounts:
{
"filters": {
"sentiment": ["positive", "neutral"],
"minXFollowers": 5000,
"engaged": false
}
}
Pattern 3: Quality Content Filter
Exclude low-quality content:
{
"filters": {
"!tag": ["spam", "irrelevant", "bot"],
"!sentiment": ["negative"]
}
}
Pattern 4: Developer Community Feedback
Get feedback from developer platforms:
{
"filters": {
"source": ["github", "stackoverflow", "hackernews", "reddit"],
"language": ["en"]
}
}
Pattern 5: Time-Bound Campaign Tracking
Track mentions during a specific campaign period:
{
"filters": {
"startDate": "2024-01-15T00:00:00Z",
"endDate": "2024-01-31T23:59:59Z",
"sentiment": ["positive", "neutral"]
}
}
Pattern 6: Competitor Keyword Exclusion
Your keywords, but not competitors:
{
"filters": {
"keyword": [1, 2],
"!keyword": [10, 11],
"source": ["twitter", "linkedin"]
}
}
Pattern 7: Multilingual Content
Content in specific languages:
{
"filters": {
"language": ["en", "es", "pt"],
"sentiment": ["positive"]
}
}
Advanced Filter Examples
Example 1: Complex Platform Logic
Get mentions from (Twitter OR LinkedIn) AND (positive OR neutral) AND NOT spam:
{
"filters": {
"operator": "AND",
"groups": [
{
"operator": "OR",
"conditions": [
{ "source": ["twitter"] },
{ "source": ["linkedin"] }
]
},
{
"operator": "OR",
"conditions": [
{ "sentiment": ["positive"] },
{ "sentiment": ["neutral"] }
]
},
{
"operator": "AND",
"conditions": [
{ "!tag": ["spam"] }
]
}
]
}
}
Example 2: Multi-Source with Follower Tiers
Different follower requirements for different platforms:
This requires multiple queries, as you can't mix follower counts for different sources in one query:
Query 1 - Twitter micro-influencers:
{
"filters": {
"source": ["twitter"],
"minXFollowers": 1000,
"maxXFollowers": 10000
}
}
Query 2 - Reddit posts (no follower filter):
{
"filters": {
"source": ["reddit"]
}
}
Example 3: Feature Request Pipeline
Unengaged positive feature requests from the last 30 days:
{
"filters": {
"operator": "AND",
"groups": [
{
"operator": "AND",
"conditions": [
{ "tag": ["feature-request"] },
{ "engaged": false },
{ "sentiment": ["positive", "neutral"] }
]
},
{
"operator": "AND",
"conditions": [
{ "startDate": "2024-01-01T00:00:00Z" }
]
}
]
}
}
Example 4: International Campaign
Multi-language positive mentions from social platforms:
{
"filters": {
"operator": "AND",
"groups": [
{
"operator": "OR",
"conditions": [
{ "source": ["twitter"] },
{ "source": ["linkedin"] },
{ "source": ["bluesky"] }
]
},
{
"operator": "OR",
"conditions": [
{ "language": ["en"] },
{ "language": ["es"] },
{ "language": ["pt"] }
]
},
{
"operator": "AND",
"conditions": [
{ "sentiment": ["positive"] }
]
}
]
}
}
Filter Optimization Tips
- Start Simple: Begin with simple mode filters and add complexity only when needed
- Use Exclusions: Often easier to exclude unwanted content than include everything wanted
- Layer Filters: Apply broad filters first (source, date), then narrow down (sentiment, tags)
- Test Incrementally: Add one filter at a time to see its effect
- Leverage Views: Save common filter combinations as views for reuse
- Check Response Counts: If you get zero results, remove filters one by one to find the issue
- Follower Filters: Apply carefully - not all platforms have follower counts
- Date Formats: Always use ISO 8601 format with timezone (Z for UTC)
Troubleshooting Filters
No Results Returned
- Check each filter individually
- Verify keyword IDs exist (call
/keywords) - Ensure date ranges are valid (startDate < endDate)
- Check for contradictory filters (e.g.,
sentiment: ["positive"]and!sentiment: ["positive"])
Too Many Results
- Add more restrictive filters (minXFollowers, sentiment)
- Narrow date range
- Exclude low-quality tags
- Use
includeAll: falseto filter out low-relevance mentions
Unexpected Results
- Check for case sensitivity in tag names
- Verify source names are lowercase
- Ensure language codes are ISO 639-1 (two-letter)
- Check that keyword IDs match your organization's keywords
API Request Examples
cURL Example
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"limit": 20,
"filters": {
"source": ["twitter"],
"sentiment": ["positive"],
"minXFollowers": 1000,
"!tag": ["spam"]
}
}'
Python Example
import requests
api_key = "YOUR_API_KEY"
url = "https://app.octolens.com/api/v1/mentions"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
payload = {
"limit": 20,
"filters": {
"source": ["twitter", "linkedin"],
"sentiment": ["positive"],
"startDate": "2024-01-01T00:00:00Z"
}
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
JavaScript Example
const apiKey = 'YOUR_API_KEY';
const url = 'https://app.octolens.com/api/v1/mentions';
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
limit: 20,
filters: {
source: ['twitter'],
sentiment: ['positive', 'neutral'],
minXFollowers: 5000
}
})
});
const data = await response.json();