API Documentation

Quick Start

The SocialRadar API provides programmatic access to our AI agent that can search, analyze, and extract insights from LinkedIn and X (Twitter).

Base URL

Authentication

All API requests require authentication via Bearer token:

Core Features

• Smart Search: Search LinkedIn posts and X tweets with advanced filters and AI-powered relevance ranking
• Sentiment Analysis: Understand audience sentiment, emotions, and engagement patterns
• Data Export: Export results as structured JSON for further processing and analysis
• Async Processing: Submit queries and poll for results, perfect for long-running searches

API Workflow

1. Submit a query to receive an execution plan
2. Approve the plan to start processing
3. Poll the status endpoint for results
4. Download generated data files

Endpoints

Submit a query and receive an execution plan.

Request

{
  "query": "Find people discussing NVIDIA negatively on X in the last week"
}

Response

{
  "threadId": "d1a30fce-22c5-4af8-8f1c-5697c3150d0d",
  "status": "awaiting_approval",
  "plan": {
    "steps": [
      {
        "id": "step-0",
        "description": "Search X for posts mentioning NVIDIA with negative sentiment",
        "status": "pending"
      }
    ],
    "totalSteps": 1
  }
}

Approve and execute the plan asynchronously.

Response

{
  "threadId": "d1a30fce-22c5-4af8-8f1c-5697c3150d0d",
  "status": "execution_started",
  "message": "Plan approved and execution started",
  "statusUrl": "https://api.socialradar.app/api/agent/status/d1a30fce...",
  "totalSteps": 1
}

Check execution status and retrieve results.

Response (Completed)

{
  "threadId": "d1a30fce-22c5-4af8-8f1c-5697c3150d0d",
  "status": "completed",
  "results": [
    {
      "step": 1,
      "description": "Search X for posts mentioning NVIDIA",
      "response": "Found 47 posts with negative sentiment about NVIDIA...",
      "completedAt": "2024-01-20T10:30:00Z"
    }
  ]
}

List all generated data files for a thread.

Download specific file content.

Code Examples

import requests
import time

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://api.socialradar.app"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Submit query
response = requests.post(
    f"{BASE_URL}/api/agent/query",
    headers=headers,
    json={"query": "Find tech influencers discussing AI on LinkedIn"}
)
data = response.json()
thread_id = data["threadId"]

# Approve plan
if data.get("plan"):
    approval = requests.post(
        f"{BASE_URL}/api/agent/approve/{thread_id}",
        headers=headers
    ).json()
    
    # Poll for results
    while True:
        status = requests.get(
            f"{BASE_URL}/api/agent/status/{thread_id}",
            headers=headers
        ).json()
        
        if status["status"] == "completed":
            print("Results:", status["results"])
            break
        
        time.sleep(2)

const API_KEY = 'sk_live_your_api_key_here';
const BASE_URL = 'https://api.socialradar.app';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function searchSocialMedia() {
  // Submit query
  const queryRes = await fetch(`${BASE_URL}/api/agent/query`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      query: 'Find tech influencers discussing AI on LinkedIn'
    })
  });
  const data = await queryRes.json();
  
  // Approve plan
  if (data.plan) {
    await fetch(`${BASE_URL}/api/agent/approve/${data.threadId}`, {
      method: 'POST',
      headers
    });
    
    // Poll for results
    let status;
    do {
      await new Promise(r => setTimeout(r, 2000));
      const statusRes = await fetch(
        `${BASE_URL}/api/agent/status/${data.threadId}`,
        { headers }
      );
      status = await statusRes.json();
    } while (status.status !== 'completed');
    
    console.log('Results:', status.results);
  }
}

# Set API key
export API_KEY="sk_live_your_api_key_here"

# Submit query
curl -X POST https://api.socialradar.app/api/agent/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Find tech influencers discussing AI on LinkedIn"}'

# Approve plan (use threadId from response)
curl -X POST https://api.socialradar.app/api/agent/approve/THREAD_ID \
  -H "Authorization: Bearer $API_KEY"

# Check status
curl https://api.socialradar.app/api/agent/status/THREAD_ID \
  -H "Authorization: Bearer $API_KEY"

Example Queries

# Find negative sentiment
"Find people complaining about Tesla customer service on X in the last month"

# Discover thought leaders
"Find LinkedIn influencers discussing quantum computing with high engagement"

# Competitive intelligence
"Search for posts comparing AWS vs Azure vs Google Cloud"

# Lead generation
"Find CTOs discussing cloud migration challenges on LinkedIn"

Rate Limits

Response Codes

200 OK              Request successful
400 Bad Request     Invalid parameters
401 Unauthorized    Invalid or missing API key
403 Forbidden       Access denied to resource
404 Not Found       Thread or resource not found
409 Conflict        Thread already processing
429 Too Many        Rate limit exceeded
500 Server Error    Internal server error