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

# Paperclip

> Install the TwexAPI Paperclip plugin for tweet search, profiles, timelines, and trending tweets in Paperclip agents.

The TwexAPI Paperclip plugin adds six read-only Twitter/X tools to [Paperclip](https://paperclip.ai) agents. It wraps documented TwexAPI REST routes with typed tool schemas, secret-backed authentication, and predictable JSON results.

Use this plugin when a Paperclip agent needs tweet search, profile lookup, user search, timeline reads, or global trending tweets without writing raw HTTP calls.

## Tools

| Agent task           | Paperclip tool            | TwexAPI route                                       |
| -------------------- | ------------------------- | --------------------------------------------------- |
| Search tweets        | `twexapi.search_tweets`   | `POST /twitter/advanced_search/page`                |
| Read one tweet       | `twexapi.lookup_tweet`    | `POST /v2/tweet/detail`                             |
| Search users         | `twexapi.search_users`    | `GET /twitter/search-user/{keyword}/{target_count}` |
| Read a profile       | `twexapi.get_user`        | `GET /twitter/{screen_name}/about`                  |
| Read profile tweets  | `twexapi.get_user_tweets` | `POST /twitter/{screen_name}/timeline/page`         |
| Read trending tweets | `twexapi.get_trends`      | `GET /twitter/global-trending/tweets`               |

This plugin does not export followers or publish posts. Use the [REST API](/api-reference/overview), [CLI](/sdks/cli), or [MCP Server](/mcp/overview) for those tasks.

## Prerequisites

* Node.js 18 or newer
* Paperclip CLI (`paperclipai`)
* A TwexAPI API key from the [dashboard](https://twexapi.io/dashboard)
* A Paperclip secret reference for the API key

## Install

```bash theme={null}
paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper
```

Pin the current release when you need reproducible installs:

```bash theme={null}
paperclipai plugin install @twexapi-dev/paperclip-plugin-x-api-scraper --version 0.1.2
```

npm: [@twexapi-dev/paperclip-plugin-x-api-scraper](https://www.npmjs.com/package/@twexapi-dev/paperclip-plugin-x-api-scraper)

Source: [twexapi-dev/paperclip-plugin-x-api-scraper](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)

## Configure

Create an API key in the [TwexAPI dashboard](https://twexapi.io/dashboard). Store it in a Paperclip secret and reference it from the plugin config.

| Setting                  | Purpose                                                      |
| ------------------------ | ------------------------------------------------------------ |
| `apiBaseUrl`             | TwexAPI REST endpoint. Defaults to `https://api.twexapi.io`. |
| `apiKeySecretRef`        | Paperclip secret reference for the TwexAPI API key.          |
| `defaultTimelineCount`   | Default timeline page count from 1 to 100.                   |
| `defaultUserSearchCount` | Default user search count from 1 to 100.                     |
| `defaultTrendCount`      | Default trend count from 1 to 100.                           |

Paperclip resolves the API key at call time and sends `Authorization: Bearer`.

Example plugin config shape:

```json theme={null}
{
  "apiBaseUrl": "https://api.twexapi.io",
  "apiKeySecretRef": "twexapi/api-key",
  "defaultTimelineCount": 20,
  "defaultUserSearchCount": 10,
  "defaultTrendCount": 20
}
```

Never commit API keys to plugin config files checked into source control.

## Example agent tasks

### Search tweets

Ask the agent to search recent posts about a topic. The plugin calls `POST /twitter/advanced_search/page` through `twexapi.search_tweets`.

Suggested prompt:

```text theme={null}
Search X for recent posts about "AI agents lang:en -filter:retweets".
Return tweet IDs, author usernames, text, and created_at for the top 10 results.
```

### Read a profile and timeline

```text theme={null}
Look up @openai, then read the latest timeline page.
Return username, user_id, follower count, and the 5 most recent tweet IDs.
```

### Read global trending tweets

```text theme={null}
Get trending tweets for United States, topic Sports, content NFL.
Summarize the top themes and list 5 representative tweet IDs.
```

## Handoff checklist

When Paperclip agents hand results to downstream systems, preserve stable identifiers.

| Data type  | Store                                                             |
| ---------- | ----------------------------------------------------------------- |
| Tweets     | `tweet_id`, `text`, `author_username`, `created_at`, search query |
| Profiles   | `user_id`, `username`, `name`, follower counts                    |
| Trends     | country, topic, content tag, tweet rows                           |
| Pagination | `next_cursor`, `has_more`, original request parameters            |

See [Agent MCP Handoff](/mcp/agent-handoff) when mixing Paperclip tools with MCP-based agents in the same workflow.

## Error handling

| Status | Action                                                  |
| ------ | ------------------------------------------------------- |
| `400`  | Fix tool input. Do not retry unchanged.                 |
| `401`  | Check the Paperclip secret reference and API key value. |
| `403`  | Check account access and credits.                       |
| `429`  | Back off before retrying.                               |
| `5xx`  | Retry with bounded backoff.                             |

## Develop locally

```bash theme={null}
git clone https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper.git
cd paperclip-plugin-x-api-scraper
pnpm install
pnpm check
```

`pnpm check` runs type checks, tests, and the build.

## Related guides

* [MCP Server](/mcp/overview)
* [CLI](/sdks/cli)
* [TypeScript SDK](/sdks/typescript)
* [OpenAPI schema](https://docs.twexapi.io/openapi.json)
* [Source repository](https://github.com/twexapi-dev/paperclip-plugin-x-api-scraper)