# First request

> Get a TwittrAPI key, make your first request with curl, Python, Node.js or Go, and check your balance.

HTML page: https://www.twittrapi.com/docs/getting-started

Video: [Get your API key and make your first request](https://www.youtube.com/watch?v=ju71Al0KPv0)

## 1. Get a key

Create an account on the [get started page](https://www.twittrapi.com/start) and copy the API key from the dashboard. New accounts get $0.50 of test credit, valid for 7 days, at 3 requests per second. Trial keys can call every read endpoint, but not the [account actions](https://www.twittrapi.com/docs/account-actions). After your first top-up the key gets the Standard rate limit. Prices are on the [pricing page](https://www.twittrapi.com/pricing).

Keep the key out of your code. The SDKs and examples read it from the `TWITTRAPI_API_KEY` environment variable:

```bash
export TWITTRAPI_API_KEY=your_key
```

## 2. Make a request

The base URL is `https://api.twittrapi.com`. Send the key in the `X-API-KEY` header. This looks up the profile of `@jack`:

```bash
curl 'https://api.twittrapi.com/user/by/username/jack' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

The response is X's JSON for that profile. The numeric user ID is in `data.user.result.rest_id`. Most other endpoints take that ID. For a one-off lookup without code, use the free [user ID finder](https://www.twittrapi.com/tools/twitter-user-id).

### Python

```bash
pip install twittrapi
```

```python
from twittrapi import TwittrAPI

client = TwittrAPI()  # reads TWITTRAPI_API_KEY
user = client.users.get_by_username("jack")
print(user["data"]["user"]["result"]["rest_id"])
```

### Node.js

```bash
npm install twittrapi
```

```js
import { TwittrAPI } from "twittrapi";

const client = new TwittrAPI(); // reads TWITTRAPI_API_KEY
const user = await client.users.getByUsername("jack");
console.log(user.data.user.result.rest_id);
```

### Go

```bash
go get github.com/twittrapi/twittrapi-go
```

```go
client, err := twittrapi.NewClient() // reads TWITTRAPI_API_KEY
if err != nil {
	log.Fatal(err)
}
user, err := client.Users.GetByUsername(context.Background(), "jack")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(user))
```

The SDKs retry 429 and 5xx responses with backoff and raise typed errors. More tools are on [SDKs and integrations](https://www.twittrapi.com/docs/integrations).

## 3. Check your balance

`GET /balance` returns your balance and price per call. It is not billed.

```bash
curl 'https://api.twittrapi.com/balance' -H 'X-API-KEY: YOUR_API_KEY'
```

Every billed response also carries `X-Remaining-Balance` and `X-Price-Per-Call` headers. See [Pricing and billing](https://www.twittrapi.com/docs/billing).

## Using RapidAPI instead

The same API is sold on [RapidAPI](https://rapidapi.com/viperscores-viperscores-default/api/twitter-aio) with monthly plans, including a free plan for testing. Paths and parameters are the same; only the host and headers change:

```bash
curl 'https://twitter-aio.p.rapidapi.com/user/by/username/jack' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
  --header 'x-rapidapi-host: twitter-aio.p.rapidapi.com'
```

The SDKs accept a RapidAPI key too (`TwittrAPI(rapidapi_key=...)`, `new TwittrAPI({ rapidApiKey })`, or the `RAPIDAPI_KEY` variable). Limits and billing for RapidAPI keys are set on RapidAPI; the balance, price tiers and rate-limit tiers on these pages apply to direct keys. The API is also listed on JojAPI; see the [get started page](https://www.twittrapi.com/start).

### Find your RapidAPI host

TwittrAPI is on RapidAPI under more than one listing, and each listing has its own host. Your key only works with the host of the listing you subscribed to. `twitter-aio.p.rapidapi.com` is the host of the Twitter AIO listing and the default everywhere.

To find yours:

1. Open the listing you subscribed to on RapidAPI.
2. Open any endpoint. The code example next to it shows the header `x-rapidapi-host`, for example `x-rapidapi-host: twitter-aio.p.rapidapi.com`.
3. Use that value as the host. The request URL starts with the same host: `https://twitter-aio.p.rapidapi.com/...`.

A 403 with "You are not subscribed to this API" usually means the host does not match the listing of your key.

### Set the host

Send the host in `x-rapidapi-host` and use it in the URL. In the SDKs and tools, set it once:

| Tool | How |
| --- | --- |
| Any SDK or tool | Environment variable `RAPIDAPI_HOST=your-listing.p.rapidapi.com` |
| Python | `TwittrAPI(rapidapi_key="...", rapidapi_host="your-listing.p.rapidapi.com")` |
| Node.js | `new TwittrAPI({ rapidApiKey, rapidApiHost: "your-listing.p.rapidapi.com" })` |
| Go | `twittrapi.NewClient(twittrapi.WithRapidAPIKey(key), twittrapi.WithRapidAPIHost("your-listing.p.rapidapi.com"))` |
| LangChain, LlamaIndex | `rapidapi_host="your-listing.p.rapidapi.com"` next to `rapidapi_key` |
| MCP server | `RAPIDAPI_HOST`; on a hosted server, the header `x-rapidapi-host` next to `x-rapidapi-key` |
| n8n | Credential field **RapidAPI Host** |
| Make | Connection field **RapidAPI host** |

Without a host, everything uses `twitter-aio.p.rapidapi.com`. You can enter the host with or without `https://`.

## Next steps

- [Errors](https://www.twittrapi.com/docs/helpful-infos/error-handling): status codes, retries and refunds.
- [Pagination](https://www.twittrapi.com/docs/helpful-infos/cursor): getting more than one page of results.
- [API reference](https://www.twittrapi.com/docs/reference): all endpoints.