> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AIsa Twitter API

> Read X/Twitter profiles, timelines, tweets, trends, and communities.

[View on GitHub ->](https://github.com/AIsa-team/agent-skills/tree/main/aisa-twitter-api)

**Twitter/X data access for agents.** Use AIsa to read profiles, timelines, tweets, trends, communities, lists, Spaces, and related social context.

## Install

First, install the AIsa CLI if you have not already:

```bash theme={null}
npm install -g @aisa-one/cli
```

Then install the skill:

```bash theme={null}
aisa skills install aisa-twitter-api
```

## What can agents do with it?

<CardGroup cols={2}>
  <Card title="Profile research" icon="user-magnifying-glass">
    Inspect users, bios, timelines, and relationships.
  </Card>

  <Card title="Tweet search" icon="magnifying-glass">
    Find tweets, trends, lists, spaces, and communities.
  </Card>

  <Card title="Audience maps" icon="users">
    Review followers, following, and network context.
  </Card>

  <Card title="Conversation context" icon="comments">
    Pull thread and Grok conversation context for analysis.
  </Card>
</CardGroup>

## When to use

* When the user wants one primary Twitter/X skill for research, monitoring, trend discovery, timeline review, or content discovery.
* When the user needs to inspect profiles, timelines, mentions, trends, replies, quotes, lists, communities, or Spaces.
* When the user wants to draft or publish posts after explicit OAuth approval without sharing passwords or browser cookies.
* When the workflow should use `AISA_API_KEY` and relay-based access to `https://api.aisa.one` instead of local credential extraction.

## When NOT to use

* Do NOT use this for password-based login, cookie extraction, or browser credential scraping.
* Do NOT use this when the workflow must avoid relay-based requests to `https://api.aisa.one`.
* Do NOT use this as the primary skill for like, follow, reply, or growth-action workflows better handled by `aisa-twitter-engagement-suite`.

## Quick Reference

* Required environment variable: `AISA_API_KEY`
* Required binary: `python3`
* Read client: `scripts/twitter_client.py`
* OAuth and posting client: `scripts/twitter_oauth_client.py`
* Posting guide: `references/post_twitter.md`
* Relay target: `https://api.aisa.one`
* External writes: posting happens only after explicit OAuth approval
* Upload behavior: image and video posting sends user-selected media through the relay

## Setup

```bash theme={null}
export AISA_API_KEY="your-key"
```

Requirements:

* `python3`
* `AISA_API_KEY`
* Internet access to `https://api.aisa.one`
* Explicit OAuth approval before posting
* User-provided media files when posting images or videos

## Capabilities

* Read user data, timelines, mentions, followers, followings, and related profile information.
* Search tweets and users, inspect replies, quotes, retweeters, thread context, trends, lists, communities, and Spaces.
* Run watchlist-style research and monitoring workflows from one Twitter/X command surface.
* Publish text, image, and video posts after explicit OAuth approval.

## High-Intent Workflows

* Research a creator, competitor, brand, or narrative before writing.
* Monitor a keyword, launch, or watchlist and pull representative tweets quickly.
* Review timelines, mentions, replies, and trend movement from one command surface.
* Draft and publish a post only after the user explicitly approves OAuth.

## Common Commands

```bash theme={null}
python3 scripts/twitter_client.py search --query "AI agents" --type Latest
python3 scripts/twitter_oauth_client.py authorize
python3 scripts/twitter_oauth_client.py post --text "Hello from AIsa"
```

## Guardrails

* Do not ask for Twitter/X passwords or browser cookies.
* Do not invent captions, tweet URLs, or attachment files.
* Do not claim external posting succeeded until the API confirms success.
* Do not imply OAuth is optional for posting.

## Example Requests

* Research what builders on X are saying about AI agents this week.
* Track reactions to our product launch and pull representative tweets.
* Build a small watchlist of competitor accounts and summarize what changed today.
* Authorize and publish a short Twitter post with an attached image.

## Security Notes

* This is a relay-based workflow that sends Twitter/X API requests to `https://api.aisa.one`.
* Posting requires explicit OAuth approval through the relay before external writes occur.
* Approved image and video posting sends user-selected media through the relay for upload.
* Required secret: `AISA_API_KEY`.
* This workflow does not require passwords or browser cookie extraction.

## Get started

1. Sign up at [aisa.one](https://aisa.one) (new accounts start with \$2 free credit).
2. Generate an API key from the console.
3. Set your key and install the skill:
   ```bash theme={null}
   export AISA_API_KEY="your-key"
   npm install -g @aisa-one/cli
   aisa skills install aisa-twitter-api
   ```
4. Start a new agent session so the runtime loads the updated skill instructions.

## Related

<CardGroup cols={3}>
  <Card title="Twitter Autopilot" icon="twitter" href="/agent-skills/twitter-autopilot">
    Full X/Twitter search and engagement workflows.
  </Card>

  <Card title="AIsa Twitter Command Center" icon="terminal" href="/agent-skills/aisa-twitter-command-center">
    Command-style X/Twitter workflows.
  </Card>

  <Card title="Twitter API reference" icon="code" href="/api-reference/twitter/get_twitter-user-info">
    X/Twitter endpoint docs.
  </Card>
</CardGroup>