Keyword Search

Create searches for keywords, hashtags, or usernames across multiple platforms.

POST /api/iq/keyword_search

Parameters

query	Required — keyword-based search (supports AND/OR/NOT and parentheses)
start_date	Optional — default: one week before current date
end_date	Optional — default: current date
platforms	Optional — array of platforms. Default: ["twitter","reddit","bluesky","youtube"]. Please use ["linkedin"] separately (Note: LinkedIn searches are slower and limited to post data only). Allowed values: twitter, reddit, bluesky, youtube, threads, facebook, linkedin
max_post	Optional — maximum number of posts per platform searched. Default: 100

Request Example

curl -X POST "https://rolli.ai/api/iq/keyword_search" \
  -H "X-ROLLI-TOKEN: your_token" \
  -H "X-ROLLI-USER-ID: your_user_id" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "AI election integrity",
  "start_date": "2025-07-01",
  "end_date": "2025-07-07",
  "max_post": 100,
  "platforms": [
    "twitter",
    "reddit",
    "bluesky",
    "youtube"
  ]
}'

fetch("https://rolli.ai/api/iq/keyword_search", {
  method: "POST",
  headers: {
    "X-ROLLI-TOKEN": "your_token",
    "X-ROLLI-USER-ID": "your_user_id",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"query":"AI election integrity","start_date":"2025-07-01","end_date":"2025-07-07","max_post":100,"platforms":["twitter","reddit","bluesky","youtube"]})
})
  .then(res => res.json())
  .then(console.log);

require "net/http"
require "uri"
require "json"

uri = URI("https://rolli.ai/api/iq/keyword_search")
req = Net::HTTP::Post.new(uri)
req["X-ROLLI-TOKEN"] = "your_token"
req["X-ROLLI-USER-ID"] = "your_user_id"
req["Content-Type"] = "application/json"
req.body = {"query":"AI election integrity","start_date":"2025-07-01","end_date":"2025-07-07","max_post":100,"platforms":["twitter","reddit","bluesky","youtube"]}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

puts res.body

import requests
import json

url = "https://rolli.ai/api/iq/keyword_search"
headers = {
    "X-ROLLI-TOKEN": "your_token",
    "X-ROLLI-USER-ID": "your_user_id",
    "Content-Type": "application/json"
}

payload = {
  "query": "AI election integrity",
  "start_date": "2025-07-01",
  "end_date": "2025-07-07",
  "max_post": 100,
  "platforms": [
    "twitter",
    "reddit",
    "bluesky",
    "youtube"
  ]
}
response = requests.post(url, json=payload, headers=headers)

print(response.json())

Response Example

{
  "id": 1241,
  "query": "an example query",
  "created_at": "2023-10-01T12:00:00Z",
  "updated_at": "2023-10-01T12:00:00Z"
}

Intelligent analysis features (metrics, sentiment, coordination) are available for Twitter only.

Coverage

Every search response, the list endpoint and the return_url callback carry coverage and notices. When a requested platform could not be searched, the search still runs on the others, and coverage says which platform was left out and why. Both fields are additive; clients that ignore them keep working.

Field Name	Description
coverage	One entry per requested platform: `{"status": "searched"}`, or `{"status": "excluded", "reason": "<code>"}`
notices	The same in plain language, one sentence per platform left out, ready to show to your users

Reason Codes

Reason	Meaning
not_connected	The platform needs a connection the account has not made
needs_reconnect	The account's connection for the platform expired; the account owner needs to reconnect it
restricted	The platform restricted the connected account
rate_limited	The connection reached its daily search limit; searches resume at 00:00 UTC
disabled_by_admin	Searching the platform this way is switched off for now
not_available	Not available for this account, or a platform that cannot run in the same search as another one requested
provider_error	The data provider did not respond for this platform

Example

{
  "coverage": {
    "twitter": { "status": "searched" },
    "reddit": { "status": "searched" },
    "instagram": { "status": "excluded", "reason": "not_connected" }
  },
  "notices": [
    "Instagram was not searched: not connected. The account owner can connect it in the Rolli API panel."
  ]
}

When none of the requested platforms can be searched, the request is answered 422 with coverage and notices, and nothing is charged.