Keyword Search Details

Retrieve the full result of a keyword-based Rolli IQ search, including analytics and statistics.

GET /api/iq/keyword_search/{id}

Parameters

Request Example

curl -X GET "https://rolli.ai/api/iq/keyword_search/1234" \
  -H "X-ROLLI-TOKEN: your_token" \
  -H "X-ROLLI-USER-ID: your_user_id" \
  -H "Content-Type: application/json"
    

fetch("https://rolli.ai/api/iq/keyword_search/1234", {
  method: "GET",
  headers: {
    "X-ROLLI-TOKEN": "your_token",
    "X-ROLLI-USER-ID": "your_user_id",
    "Content-Type": "application/json"
  },
})
  .then(res => res.json())
  .then(console.log);
    

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

uri = URI("https://rolli.ai/api/iq/keyword_search/1234")
req = Net::HTTP::Get.new(uri)
req["X-ROLLI-TOKEN"] = "your_token"
req["X-ROLLI-USER-ID"] = "your_user_id"
req["Content-Type"] = "application/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/1234"
headers = {
    "X-ROLLI-TOKEN": "your_token",
    "X-ROLLI-USER-ID": "your_user_id",
    "Content-Type": "application/json"
}response = requests.get(url, headers=headers)

print(response.json())
    

Response Fields

results Fields

breakout_moment Fields

co_occurrence Fields

indicator_of_coordination Fields

metric.twitter Fields

posts and tweet_preview Fields

Example Response

  {
    "id": 1241,
    "query": "an example query",
    "created_at": "2023-10-01T12:00:00Z",
    "updated_at": "2023-10-01T12:00:00Z",
    "status": "finished",
    "status_percentage": "100",
    "status_text": "Finished data collection.",
    "tweet_preview": [
      {
        "d": "How can people be expected to have faith in Trump if he won’t release the Epstein files?",
        "i": 623174,
        "l": "https://twitter.com/elonmusk/status/1942653394168246464",
        "n": "elonmusk",
        "p": "https://pbs.twimg.com/profile_images/1936002956333080576/kqqe2iWO_normal.jpg",
        "t": "2025-07-08T18:33:56",
        "u_d": "",
        "u_id": "44196397",
        "u_t": "2009-06-02T20:12:29"
      }
    ],
    "results": {
      "breakout_moment": [
        {
          "height": 8.934110267827556,
          "summary": "Key discussion point: Trump is openly calling for the deportation and arrest of U.S. citizens, including NYC Mayoral Candidate Mamdani, which raises concerns about fascism and misuse of power.",
          "time": "2025-07-01 16:39:55"
        }
      ],
      "co_occurrence": [
        {
          "count": 34,
          "name": "#trump",
          "platform": "youtube",
          "type": "hashtag"
        },
        {
          "count": 20,
          "name": "#news",
          "platform": "youtube",
          "type": "hashtag"
        },
        {
          "count": 16,
          "name": "https://www.msnbc.com/",
          "platform": "youtube",
          "type": "url"
        },
        {
          "count": 9,
          "name": "http://www.foxnewsgo.com/",
          "platform": "youtube",
          "type": "url"
        }
      ],
      "created_at": "Wed, 02 Jul 2025 15:19:58 GMT",
      "id_hash256": "cd238f46c4eddb5f83984e20867eb812eec4354022151ff655d38dce4b879bd2",
      "indicator_of_coordination": {
        "coordination_score": 10,
        "frequent_posters_bluesky": {
          "context": "Average bluesky post per user is 0. This is within normal range .Top 10% users are ",
          "verdict": false
        },
        "frequent_posters_reddit": {
          "context": "Average reddit post per user is 3.23. This is beyond normal range .Top 10% users are politics, NoShitSherlock, ...",
          "verdict": true
        },
        "frequent_posters_twitter": {
          "context": "Average tweet per user is 1.45\n Percent of tweets from top 10% user is 30.0%\n Top 10% users are charliekirk11, ...",
          "verdict": false
        },
        "frequent_posters_youtube": {
          "context": "Average youtube post per user is 1.79. This is within normal range .Top 10% users are MSNBC, ...",
          "verdict": false
        },
        "twitter_new_account_percent": {
          "context": "Percent of twitter account created after 2021 is 19. This is within normal range.",
          "verdict": false
        }
      },
      "interaction": {
        "bluesky": 0,
        "instagram": 0,
        "reddit": 2838850,
        "twitter": 4654849,
        "youtube": 1098860
      },
      "metric": {
        "twitter": {
          "account_created_after_2021": 19,
          "avg_post_per_user": 1.45,
          "percent_post_from_top_10_percent_user": 30.0,
          "top_10_user": [
            "charliekirk11",
            "bennyjohnson",
            "EricLDaugh",
            "nicksortor",
            "EndWokeness",
            "StephenM",
            "PopCrave"
          ]
        }
      },
      "posts": {
        "bluesky": [],
        "reddit": [
          {
            "comment": 0,
            "d": "Trump calls for deporting US citizens: \"We also have a lot of bad people that have been here for a long time ... many of them were born in our country. I think we ought to get them the hell out of here too, if you want to know the truth. So maybe that'll be the next job.\"",
            "i": 81363,
            "l": "https://www.reddit.com/r/law/comments/1lp758g/trump_calls_for_deporting_us_citizens_we_also/",
            "like": 0,
            "n": "law",
            "p": "https://external-preview.redd.it/bno5Y2c1dnhuYWFmMdXIsHa1Y7IDdsrku4c7Rj6QtgJdQ3qT_E4IiEfDDxy5.png?width=140&height=78&crop=140:78,smart&format=jpg&v=enabled&lthumb=true&s=e04b07f88d82d44998660419b76153bca8d75570",
            "t": "2025-07-01T17:03:45",
            "view": 0
          }
        ],
        "twitter": [
          {
            "comment": 307,
            "d": "fucking crying my eyes out it still looks like optimus prime kills donald trump here thank you optimus prime",
            "i": 316123,
            "l": "https://twitter.com/thediegocrespo/status/1939490201107382761",
            "like": 293724,
            "n": "thediegocrespo",
            "p": "https://pbs.twimg.com/profile_images/1900203770086383617/C6ADsZmR_normal.jpg",
            "t": "2025-06-30T01:04:32",
            "u_d": "Making things. Host of @thewafflepress. [email protected] He/Him.",
            "u_id": "397433002",
            "u_loc": "Los Angeles",
            "u_t": "2011-10-24T17:46:55",
            "view": 0
          }
        ],
        "youtube": [
          {
            "comment": 0,
            "d": "WATCH LIVE: House votes on Trump's ‘big, beautiful’ tax and spending bill after Senate passage __ Watch PBS News for daily, breaking and live news, plus special coverage. We are home to PBS News Hour, ranked the most credible and objective TV news show.\n\nSubscribe for exclusive content in our newsletters: https://www.pbs.org/newshour/subscribe\nPBS News podcasts: https://www.pbs.org/newshour/podcasts\nStream your PBS favorites with the PBS app: https://to.pbs.org/2Jb8twG\nFind more from PBS News at https://www.pbs.org/newshour\nSubscribe to our YouTube channel: https://bit.ly/2HfsCD6\n\nFollow us:\nTikTok: https://www.tiktok.com/@pbsnews\nX: http://www.twitter.com/newshour \nInstagram: http://www.instagram.com/newshour\nFacebook: http://www.pbs.org/newshour",
            "i": 426,
            "l": "https://www.youtube.com/watch?v=IH3XSPzoESc",
            "like": 426,
            "n": "PBS NewsHour",
            "p": "https://i.ytimg.com/vi/IH3XSPzoESc/default_live.jpg",
            "t": "2025-07-02T12:59:16",
            "view": 26144
          }
        ],
        "youtube_comment": []
      },
      "query": "trump",
      "sentiment": {
        "bluesky": "Unknown",
        "reddit": "Negative",
        "twitter": "Mixed",
        "youtube": "Mixed"
      },
      "summary": {
        "bluesky": "Unkonwn. Not enough text to process.",
        "reddit": "The overall sentiment is Negative.  The majority of the posts express negative sentiments towards Trump, his policies, and his administration. For example, posts mention Trump's corruption, threats of deportations, and negative impacts on various groups of people.",
        "twitter": "The overall sentiment is Mixed.  The sentiment is mixed as there are posts expressing support for Trump's actions and decisions, while others criticize him and his administration. For example, some posts praise Trump for keeping his promises and taking strong actions, while others condemn his policies and statements as harmful or dangerous.",
        "youtube": "The overall sentiment is Mixed  The sentiment is mixed with some posts being negative towards Trump, such as \"Trump Drops The F-Bomb\" and \"Trump has COGNITIVE MELTDOWN at Presser,\" while others are more positive, like \"President Trump stops to watch the United States Marine Band play God Bless America.\""
      }
    }
  }
  

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.

Reason Codes

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.