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

# Vercel AI SDK

> Give AI SDK agents read-only X (Twitter) data with @twitterapi_io/ai-sdk: tweet search, profiles, timelines, mentions, threads and trends.

`@twitterapi_io/ai-sdk` packages twitterapi.io endpoints as [AI SDK](https://ai-sdk.dev) tools. Pass them to `generateText`, `streamText` or an agent, and the model can search X and read profiles, timelines, mentions, conversation threads and trends on its own. All tools are read-only.

## 1. Install

```bash theme={null}
npm install @twitterapi_io/ai-sdk ai zod
```

Works with AI SDK v5 and later.

## 2. Set your API key

Get a key on the [dashboard](https://twitterapi.io/dashboard) and set it as an environment variable:

```bash theme={null}
export TWITTERAPI_IO_API_KEY="your_key"
```

## 3. Use the tools

```ts theme={null}
import { generateText, isStepCount } from 'ai';
import { twitterApiIoTools } from '@twitterapi_io/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  prompt: 'What are developers on X saying about the Vercel AI SDK this week? Cite tweet links.',
  tools: twitterApiIoTools(),
  stopWhen: isStepCount(5),
});

console.log(text);
```

On AI SDK v5 and v6, use `stepCountIs(5)` instead of `isStepCount(5)`.

To give the model only some tools, import them one by one:

```ts theme={null}
import { searchTweets, getUserProfile } from '@twitterapi_io/ai-sdk';

const tools = {
  searchTweets: searchTweets(),
  getUserProfile: getUserProfile(),
};
```

## Tools

| Tool | Endpoint | What the model gets |
| - | - | - |
| `searchTweets` | [Advanced search](/api-reference/endpoint/tweet_advanced_search) | Tweets matching a query with X search operators (`from:`, `to:`, `"phrase"`, `lang:`, `since:`, `min_faves:` ...); `Latest` or `Top` |
| `getUserProfile` | [User info](/api-reference/endpoint/get_user_by_username) | Name, bio, location, follower / following / post counts, verification |
| `getUserTweets` | [User last tweets](/api-reference/endpoint/get_user_last_tweets) | An account's most recent posts, optionally with replies |
| `getUserMentions` | [User mentions](/api-reference/endpoint/get_user_mention) | Posts that mention an account, optionally within a time window |
| `getTweetsByIds` | [Tweets by IDs](/api-reference/endpoint/get_tweet_by_ids) | Up to 100 posts by ID |
| `getTweetThread` | [Thread context](/api-reference/endpoint/get_tweet_thread_context) | The conversation around a post |
| `getTrends` | [Trends](/api-reference/endpoint/get_trends) | Trending topics for a location (WOEID; 1 = worldwide) |

Paginated tools return `{ tweets, hasNextPage, nextCursor }`, and the model passes `nextCursor` back as `cursor` for the next page. Tweets come back in a compact shape (id, url, text, createdAt, author, engagement counts, reply and thread ids) to keep token use low.

Each tool call costs the same credits as the endpoint it calls; see [Pricing](/pricing).

## Options

```ts theme={null}
twitterApiIoTools({
  apiKey: process.env.MY_KEY, // default: process.env.TWITTERAPI_IO_API_KEY
  baseUrl: 'https://api.twitterapi.io', // default
});
```

Errors such as an invalid key or an unknown user are thrown as `TwitterApiIoError` with an HTTP `status`, and the AI SDK reports them to the model as tool errors.

## Security

* Tool results are posts written by X users. Each tool description tells the model to treat them as data, never as instructions; repeat that rule in your system prompt.
* Keep the API key in an environment variable, not in source code.

## Links

* npm: [@twitterapi\_io/ai-sdk](https://www.npmjs.com/package/@twitterapi_io/ai-sdk)
* Source: [github.com/kaitoInfra/twitterapi-io-ai-sdk](https://github.com/kaitoInfra/twitterapi-io-ai-sdk)
* Prefer MCP? Connect any MCP client to `https://mcp.twitterapi.io/mcp`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.