13 KiB
Octolens API Usage Examples
This document provides real-world examples and workflows for common Octolens API use cases.
Table of Contents
- Basic Queries
- Sentiment Analysis
- Influencer Tracking
- Competitor Monitoring
- Campaign Tracking
- Product Feedback Collection
- Multi-Platform Analysis
- Pagination Workflows
Basic Queries
Example 1: Get Latest Mentions
Fetch the 20 most recent mentions:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 20
}'
Example 2: List All Keywords
curl "https://app.octolens.com/api/v1/keywords" \
-H "Authorization: Bearer ${API_KEY}"
Response:
{
"data": [
{"id": 1, "keyword": "MyProduct", "platforms": ["twitter", "reddit"]},
{"id": 2, "keyword": "MyBrand", "platforms": ["twitter", "linkedin"]},
{"id": 3, "keyword": "CompetitorA", "platforms": ["twitter"]}
]
}
Example 3: List Saved Views
curl "https://app.octolens.com/api/v1/views" \
-H "Authorization: Bearer ${API_KEY}"
Sentiment Analysis
Example 4: Positive Mentions Only
Get all positive sentiment mentions:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"filters": {
"sentiment": ["positive"]
}
}'
Example 5: Negative Feedback Analysis
Get negative mentions to identify issues:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 30,
"filters": {
"sentiment": ["negative"],
"engaged": false
}
}'
Example 6: Sentiment Distribution
Get equal samples of each sentiment:
Positive:
{"limit": 20, "filters": {"sentiment": ["positive"]}}
Neutral:
{"limit": 20, "filters": {"sentiment": ["neutral"]}}
Negative:
{"limit": 20, "filters": {"sentiment": ["negative"]}}
Then aggregate and analyze the distribution.
Influencer Tracking
Example 7: High-Follower Positive Mentions
Find positive mentions from accounts with 10k+ followers:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 25,
"filters": {
"sentiment": ["positive"],
"minXFollowers": 10000,
"source": ["twitter"]
}
}'
Example 8: Micro-Influencer Engagement
Target micro-influencers (1k-10k followers):
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"filters": {
"minXFollowers": 1000,
"maxXFollowers": 10000,
"sentiment": ["positive", "neutral"],
"engaged": false
}
}'
Example 9: Macro-Influencer Mentions
Track macro-influencers (100k+ followers):
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 10,
"filters": {
"minXFollowers": 100000,
"source": ["twitter", "linkedin"]
}
}'
Competitor Monitoring
Example 10: Track Competitor Mentions
Assuming keyword ID 5 is a competitor:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 30,
"filters": {
"keyword": [5],
"sentiment": ["negative"]
}
}'
Example 11: Compare Your Brand vs Competitor
Your mentions:
{
"limit": 50,
"filters": {
"keyword": [1],
"sentiment": ["positive"]
}
}
Competitor mentions:
{
"limit": 50,
"filters": {
"keyword": [5],
"sentiment": ["positive"]
}
}
Compare counts and sentiment distribution.
Example 12: Exclude Competitor Noise
Get your mentions, excluding competitor discussions:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 40,
"filters": {
"keyword": [1, 2],
"!keyword": [5, 6, 7]
}
}'
Campaign Tracking
Example 13: Product Launch Campaign
Track mentions during launch week:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 100,
"filters": {
"startDate": "2024-01-15T00:00:00Z",
"endDate": "2024-01-21T23:59:59Z",
"source": ["twitter", "linkedin", "hackernews"]
}
}'
Example 14: Daily Campaign Monitoring
Get today's mentions (generate date dynamically):
#!/bin/bash
TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"limit\": 50,
\"filters\": {
\"startDate\": \"$TODAY\"
}
}"
Example 15: Weekly Digest
Get last 7 days of positive mentions:
#!/bin/bash
SEVEN_DAYS_AGO=$(date -u -v-7d +"%Y-%m-%dT%H:%M:%SZ")
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"limit\": 100,
\"filters\": {
\"startDate\": \"$SEVEN_DAYS_AGO\",
\"sentiment\": [\"positive\"]
}
}"
Product Feedback Collection
Example 16: Feature Request Identification
Get mentions tagged as feature requests:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"filters": {
"tag": ["feature-request"],
"source": ["twitter", "reddit", "github"]
}
}'
Example 17: Bug Reports
Find potential bug reports (negative sentiment + specific sources):
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 30,
"filters": {
"sentiment": ["negative"],
"source": ["github", "stackoverflow", "reddit"],
"!tag": ["spam"]
}
}'
Example 18: Unengaged High-Priority Feedback
Find important feedback you haven't responded to:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 20,
"filters": {
"engaged": false,
"minXFollowers": 1000,
"sentiment": ["positive", "neutral"],
"!tag": ["spam", "irrelevant"]
}
}'
Multi-Platform Analysis
Example 19: Developer Community Mentions
Get mentions from developer platforms:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"filters": {
"source": ["github", "stackoverflow", "hackernews", "devto"],
"language": ["en"]
}
}'
Example 20: Social Media vs Forums
Compare social media and forum discussions:
Social media:
{
"limit": 50,
"filters": {
"source": ["twitter", "linkedin", "bluesky"]
}
}
Forums:
{
"limit": 50,
"filters": {
"source": ["reddit", "hackernews", "stackoverflow"]
}
}
Example 21: Exclude Low-Quality Platforms
Focus on high-quality sources:
curl -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 40,
"filters": {
"source": ["twitter", "linkedin", "hackernews"],
"!tag": ["spam", "bot"],
"minXFollowers": 500
}
}'
Pagination Workflows
Example 22: Fetch All Results with Pagination
#!/bin/bash
API_KEY="your_api_key_here"
CURSOR=""
PAGE=1
while true; do
echo "Fetching page $PAGE..."
if [ -z "$CURSOR" ]; then
RESPONSE=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 100,
"filters": {"sentiment": ["positive"]}
}')
else
RESPONSE=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"limit\": 100,
\"cursor\": \"$CURSOR\",
\"filters\": {\"sentiment\": [\"positive\"]}
}")
fi
# Extract data
echo "$RESPONSE" | jq '.data[]' >> all_mentions.json
# Get next cursor
NEXT_CURSOR=$(echo "$RESPONSE" | jq -r '.cursor // empty')
if [ -z "$NEXT_CURSOR" ]; then
echo "No more pages. Done!"
break
fi
CURSOR="$NEXT_CURSOR"
PAGE=$((PAGE + 1))
# Rate limit protection
sleep 1
done
Example 23: Collect Until Date
Fetch mentions until reaching a specific date:
#!/bin/bash
API_KEY="your_api_key_here"
TARGET_DATE="2024-01-01T00:00:00Z"
CURSOR=""
while true; do
if [ -z "$CURSOR" ]; then
RESPONSE=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{"limit": 100}')
else
RESPONSE=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"limit\": 100, \"cursor\": \"$CURSOR\"}")
fi
# Get oldest timestamp in this page
OLDEST=$(echo "$RESPONSE" | jq -r '.data[-1].timestamp // empty')
if [ -z "$OLDEST" ]; then
echo "No more data"
break
fi
# Save data
echo "$RESPONSE" | jq '.data[]' >> mentions.json
# Check if we've reached target date
if [[ "$OLDEST" < "$TARGET_DATE" ]]; then
echo "Reached target date: $TARGET_DATE"
break
fi
CURSOR=$(echo "$RESPONSE" | jq -r '.cursor // empty')
if [ -z "$CURSOR" ]; then
break
fi
sleep 1
done
Advanced Workflows
Example 24: Sentiment Analysis Report
Generate a sentiment report:
#!/bin/bash
API_KEY="your_api_key_here"
echo "Fetching sentiment data..."
POSITIVE=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{"limit": 100, "filters": {"sentiment": ["positive"]}}' \
| jq '.data | length')
NEUTRAL=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{"limit": 100, "filters": {"sentiment": ["neutral"]}}' \
| jq '.data | length')
NEGATIVE=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{"limit": 100, "filters": {"sentiment": ["negative"]}}' \
| jq '.data | length')
TOTAL=$((POSITIVE + NEUTRAL + NEGATIVE))
echo "Sentiment Report:"
echo "================="
echo "Positive: $POSITIVE ($((POSITIVE * 100 / TOTAL))%)"
echo "Neutral: $NEUTRAL ($((NEUTRAL * 100 / TOTAL))%)"
echo "Negative: $NEGATIVE ($((NEGATIVE * 100 / TOTAL))%)"
echo "Total: $TOTAL"
Example 25: Top Influencers Report
Find top influencers mentioning your brand:
#!/bin/bash
API_KEY="your_api_key_here"
curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"limit": 100,
"filters": {
"minXFollowers": 10000,
"sentiment": ["positive", "neutral"]
}
}' | jq -r '.data[] | "\(.authorFollowers)\t\(.authorName)\t\(.url)"' \
| sort -rn \
| head -20
Example 26: Daily Alert for Negative Mentions
Set up a daily alert:
#!/bin/bash
API_KEY="your_api_key_here"
TODAY=$(date -u +"%Y-%m-%dT00:00:00Z")
NEGATIVE_COUNT=$(curl -s -X POST "https://app.octolens.com/api/v1/mentions" \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"limit\": 100,
\"filters\": {
\"sentiment\": [\"negative\"],
\"startDate\": \"$TODAY\"
}
}" | jq '.data | length')
if [ "$NEGATIVE_COUNT" -gt 0 ]; then
echo "⚠️ Alert: $NEGATIVE_COUNT negative mentions today!"
# Send notification (e.g., email, Slack, etc.)
else
echo "✅ No negative mentions today"
fi
Tips for Complex Queries
- Break down complex requirements: Start with simple filters, then combine
- Test incrementally: Add one filter at a time
- Use jq for analysis: Pipe responses through jq for data extraction
- Cache keyword IDs: Fetch once, reuse in filters
- Handle pagination: Always check for cursor in responses
- Rate limit awareness: Add delays between requests in loops
- Date calculations: Use shell date utilities for dynamic date ranges
- Combine with views: Start with a view, then add additional filters