search-operations

Unlocking Insights with the Comprehensive Twitter Data Access API

24 Jul 2025
Unlocking Insights with the Comprehensive Twitter Data Access API

The Comprehensive Twitter Data Access API provides developers with powerful tools to extract, analyze, and interact with Twitter data seamlessly. This API offers a suite of Cognitive Actions that allow for in-depth exploration of tweets, user interactions, and media content. By leveraging this API, developers can enhance their applications with real-time data insights, improve user engagement, and automate various social media functionalities.

Use Cases

  • Social Media Analytics: Track trends and analyze the performance of tweets based on user engagement metrics such as likes and retweets.
  • Content Curation: Gather relevant tweets around specific topics or hashtags to curate content for newsletters, blogs, or social media feeds.
  • User Engagement: Retrieve user-generated content to understand audience preferences and improve interaction strategies.
  • Research: Conduct studies on public sentiment, trending topics, or the spread of information in real-time.

To get started, you will need a Cognitive Actions API key and a basic understanding of how to make API calls.

Retrieve Search Continuation Results

The Retrieve Search Continuation Results action fetches additional tweets based on specified search criteria. This action is particularly useful for developers looking to explore more content related to a specific query without having to reinitiate the search process.

  • Purpose: This action enables users to explore additional tweets based on previous search queries, providing features like filtering by likes, retweets, language, and more for precise data gathering.
  • Input Requirements:
    • limit: The maximum number of results to return (default is 5).
    • query: The search query string, such as a hashtag or keyword (e.g., #python).
    • section: The specific section to search for results, for example, 'top' or 'recent'.
    • language: The language code for the desired results (e.g., en for English).
    • minLikes: The minimum number of likes a result should have to be included (default is 20).
    • minRetweets: The minimum number of retweets a result should have to be included (default is 20).
    • beginningDate: The start date for the search query in 'YYYY-MM-DD' format.
    • nextPageToken: A token used for retrieving the next page of results.
  • Expected Output: The response includes a list of tweets that meet the specified criteria, along with engagement metrics such as likes, retweets, and user information.
{
  "results": [
    {
      "text": "Sample tweet content",
      "user": {
        "name": "User Name",
        "username": "user_handle",
        "followers_count": 1000
      },
      "likes": 150,
      "retweets": 30,
      "timestamp": "2023-01-01T00:00:00Z"
    }
  ],
  "continuation_token": "next_page_token_here"
}
  • Use Cases:
    • When you want to continue browsing tweets for a specific hashtag after an initial search.
    • For applications that require continuous updates on trending topics or events.

```python
import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "551cc55f-b1c1-4e02-a147-7276389816f0" # Action ID for: Retrieve Search Continuation Results

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "limit": 5,
  "query": "#python",
  "section": "top",
  "language": "en",
  "minLikes": 20,
  "minRetweets": 20,
  "beginningDate": "2022-01-01",
  "nextPageToken": "DAACCgACF_Sz76EAJxAKAAMX9LPvoP_Y8AgABAAAAAILAAUAAABQRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUFVWDlJWmx4cHZBZkJmMG5RNUxHdUVQRi9TdTZPSGJzQ0VYOUp6Y3psdUJ3UmYwbFE3Q1dxQWsIAAYAAAAACAAHAAAAAAwACAoAARf0hmXGm8B8AAAA"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Fetch User Tweets by Username
The **Fetch User Tweets by Username** action allows developers to retrieve a list of tweets posted by a specific user, providing the option to include pinned tweets and replies.

- **Purpose:** This action helps in gathering all relevant content from a user, making it easier to analyze their tweeting behavior or to display their tweets in applications.
- **Input Requirements:**
  - `limit`: Specifies the maximum number of results to return (default is 40).
  - `userId`: A string that uniquely identifies the user (default is `44196397`).
  - `username`: The handle or alias of the user (e.g., `elonmusk`).
  - `includePinned`: A boolean flag to include pinned items in the results (default is false).
  - `includeReplies`: A boolean flag to include replies in the results (default is false).

- **Expected Output:** The response will contain a list of tweets by the specified user, along with engagement metrics and metadata.

```json
{
  "results": [
    {
      "text": "User tweet content",
      "user": {
        "name": "User Name",
        "username": "user_handle",
        "followers_count": 1000
      },
      "timestamp": "2023-01-01T00:00:00Z",
      "likes": 150
    }
  ]
}
  • Use Cases:
    • Ideal for applications that showcase a user's latest tweets, such as personal dashboards or fan pages.
    • Useful for analyzing user sentiment and engagement based on their tweet history.

```python
import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "7a1ed2d7-432a-4c3f-9128-6ffb48542cfb" # Action ID for: Fetch User Tweets by Username

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "limit": 40,
  "userId": "44196397",
  "username": "elonmusk"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Retrieve User Media
The **Retrieve User Media** action allows developers to fetch a list of media content associated with a specific user ID, enhancing user profiles with rich media.

- **Purpose:** This action allows applications to display all media content shared by a user, enriching the user experience by showcasing their visual content.
- **Input Requirements:**
  - `maxResults`: Specifies the maximum number of results to return (default is 10).
  - `userIdentifier`: A unique string that identifies the user (default is `44196397`).

- **Expected Output:** The response will include media items such as images or videos associated with the user.

```json
{
  "results": [
    {
      "media_url": "https://link_to_media.com",
      "description": "Media description",
      "timestamp": "2023-01-01T00:00:00Z"
    }
  ]
}
  • Use Cases:
    • Perfect for applications that curate user-generated content, like portfolios or social media aggregators.
    • Useful for enhancing user profiles on platforms that leverage visual storytelling.

```python
import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "8a6766a0-9e74-4d31-b699-6f129d3fc787" # Action ID for: Retrieve User Media

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "maxResults": 10,
  "userIdentifier": "44196397"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Retrieve Twitter Search Results
The **Retrieve Twitter Search Results** action allows developers to gather detailed search results from Twitter, encompassing tweets, users, videos, and more based on specific search queries.

- **Purpose:** This action facilitates comprehensive searches through Twitter's vast data, enabling developers to extract relevant content based on keywords and filters.
- **Input Requirements:**
  - `limit`: The maximum number of results to return (default is 5).
  - `query`: The search term or hashtag to look for in the dataset (e.g., `#python`).
  - `section`: The content section from which to retrieve data (e.g., 'top', 'latest').
  - `language`: The language code for filtering results.
  - `minLikes`: The minimum number of likes required for results.
  - `initialDate`: The starting date for filtering results.
  - `minRetweets`: The minimum number of retweets required for results.

- **Expected Output:** The output will consist of tweets that match the search criteria, along with metadata about each tweet.

```json
{
  "results": [
    {
      "text": "Tweet content",
      "user": {
        "name": "User Name",
        "username": "user_handle"
      },
      "likes": 150,
      "retweets": 30,
      "timestamp": "2023-01-01T00:00:00Z"
    }
  ]
}
  • Use Cases:
    • Ideal for news aggregators or applications that need to display trending topics based on real-time data.
    • Useful for sentiment analysis and public opinion research.

```python
import requests
import json

# Replace with your actual Cognitive Actions API key and endpoint
# Ensure your environment securely handles the API key
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
# This endpoint URL is hypothetical and should be documented for users
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"

action_id = "8b5c8e60-dcc2-4dcf-aecd-bcd3b3dc027a" # Action ID for: Retrieve Twitter Search Results

# Construct the exact input payload based on the action's requirements
# This example uses the predefined example_input for this action:
payload = {
  "limit": 5,
  "query": "#python",
  "section": "top",
  "language": "en",
  "minLikes": 20,
  "initialDate": "2022-01-01",
  "minRetweets": 20
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json",
    # Add any other required headers for the Cognitive Actions API
}

# Prepare the request body for the hypothetical execution endpoint
request_body = {
    "action_id": action_id,
    "inputs": payload
}

print(f"--- Calling Cognitive Action: {action.name or action_id} ---")
print(f"Endpoint: {COGNITIVE_ACTIONS_EXECUTE_URL}")
print(f"Action ID: {action_id}")
print("Payload being sent:")
print(json.dumps(request_body, indent=2))
print("------------------------------------------------")

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json=request_body
    )
    response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully. Result:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body (non-JSON): {e.response.text}")
    print("------------------------------------------------")



## Conclusion
The Comprehensive Twitter Data Access API offers a robust set of tools for developers looking to harness the power of Twitter data. By integrating these Cognitive Actions, you can enhance user engagement, streamline content curation, and perform insightful analysis. Whether you're building analytics platforms, social media dashboards, or research tools, the potential applications are vast and impactful.

Your next steps could involve experimenting with these actions, exploring their capabilities, and integrating them into your applications to unlock the full potential of Twitter data.
← Back to All Articles