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

# Quickstart

> Get your API key and make your first request to the X (Twitter) API in minutes.

This guide takes you from zero to your first response: create an account, authenticate, then run your first `GET` and `POST` requests. Each step includes working examples in cURL, Python, and JavaScript.

## Step 1: Get your API key

1. Open the [Sorsa Dashboard](https://api.sorsa.io/overview) and click **Sign in**. Register with any available option. Sorsa asks for nothing beyond what your auth provider shares.
2. Your account starts with **100 free requests**. No card required, they work on all 40 endpoints, and they never expire, so you can start testing immediately.
3. When you need more volume, choose a plan (10K, 100K, or 500K requests per month) and a billing cycle (monthly or yearly), then pay by card or crypto.

Once you are signed in, the dashboard shows your **API key** and your **remaining request quota**.

> **Keep your API key private.** Never expose it in frontend code, public repositories, or client-side JavaScript. Treat it like a password.

## Step 2: Understand the basics

A few things to know before your first call.

**Base URL**

```text theme={null}
https://api.sorsa.io/v3
```

**Authentication**

Every request must include your API key in the `ApiKey` header:

```text theme={null}
ApiKey: YOUR_API_KEY
```

**Response format**

All endpoints return JSON. A successful request responds with HTTP `200`.

**Rate limit**

Every plan shares a limit of 20 requests per second. See [Rate Limits](https://docs.sorsa.io/rate-limits) for the relevant headers and a retry strategy.

## Step 3: Send your first GET request

The quickest way to confirm your setup is to fetch a public profile with the `/info` endpoint.

**cURL**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Python**

```python theme={null}
import requests

response = requests.get(
    "https://api.sorsa.io/v3/info",
    params={"username": "elonmusk"},
    headers={"ApiKey": "YOUR_API_KEY"},
)

data = response.json()
print(data["display_name"])      # Elon Musk
print(data["followers_count"])   # 236021252
```

**JavaScript**

```javascript theme={null}
const response = await fetch(
  "https://api.sorsa.io/v3/info?username=elonmusk",
  { headers: { ApiKey: "YOUR_API_KEY" } }
);

const data = await response.json();
console.log(data.display_name);      // Elon Musk
console.log(data.followers_count);   // 236021252
```

**Example response**

```json theme={null}
{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "",
  "location": "",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1234567890/avatar.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/1700000000",
  "followers_count": 236021252,
  "followings_count": 1292,
  "tweets_count": 98479,
  "favourites_count": 214650,
  "media_count": 4374,
  "verified": true,
  "protected": false,
  "can_dm": false,
  "possibly_sensitive": false,
  "created_at": "2009-06-02T20:12:29Z",
  "bio_urls": [],
  "pinned_tweet_ids": ["2028500984977330453"]
}
```

If you get JSON with user data back, your key works and you are ready to go.

## Step 4: Send your first POST request

Many tweet and search endpoints use `POST` with a JSON body. Here is a tweet search with `/search-tweets`:

**cURL**

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "bitcoin" }'
```

**Python**

```python theme={null}
import requests

response = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": "bitcoin"},
)

data = response.json()
for tweet in data.get("tweets", []):
    print(tweet["full_text"])
```

**JavaScript**

```javascript theme={null}
const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: {
    ApiKey: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "bitcoin" }),
});

const data = await response.json();
data.tweets?.forEach((tweet) => console.log(tweet.full_text));
```

**Example response (truncated)**

```json theme={null}
{
  "tweets": [
    {
      "id": "1782368585664626774",
      "full_text": "Bitcoin just crossed another milestone.",
      "created_at": "2024-01-15T10:30:00Z",
      "lang": "en",
      "likes_count": 200,
      "retweet_count": 50,
      "reply_count": 10,
      "view_count": 10000,
      "user": {
        "id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "followers_count": 236021252,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABF7d..."
}
```

To page through more results, pass the returned `next_cursor` in your next request. See [Pagination](https://docs.sorsa.io/pagination) for the full pattern.

## Step 5: Check your API usage

Check how many requests you have left at any time with `/key-usage-info`:

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/key-usage-info' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Example response**

```json theme={null}
{
  "key_requests": 100000,
  "remaining_requests": 94231,
  "total_requests": 5769,
  "valid_until": "2026-08-01T00:00:00Z"
}
```

It is good practice to call this before running large batch jobs. You can also review your full history in the [Dashboard](https://api.sorsa.io/overview/usage).

## Common error codes

| Code | Meaning           | What to do                                                     |
| :--- | :---------------- | :------------------------------------------------------------- |
| 200  | OK                | Request succeeded                                              |
| 400  | Bad request       | Check your query parameters and request body                   |
| 401  | Unauthorized      | Your API key is missing or invalid; verify the `ApiKey` header |
| 403  | Forbidden         | Access to this resource is denied                              |
| 404  | Not found         | Check the endpoint URL or the resource ID                      |
| 429  | Too many requests | You hit the rate limit; wait and retry                         |
| 500  | Server error      | Retry after a short delay; contact support if it persists      |

For full details and handling strategies, see the [Error Codes Reference](https://docs.sorsa.io/error-codes).

## Try it without code

Prefer to click around first? Explore every endpoint in the [API Reference](https://docs.sorsa.io/api-reference-guide) or use the no-code [API Playground](https://api.sorsa.io/playground). Both let you send real requests and inspect responses before writing a line of code.

## Next steps

* [Authentication](https://docs.sorsa.io/authentication) - Security best practices and header configuration
* [Pagination](https://docs.sorsa.io/pagination) - Handling cursors and paginated responses
* [Rate Limits](https://docs.sorsa.io/rate-limits) - Rate limit headers and retry strategies
* [API Reference](https://docs.sorsa.io/api-reference-guide) - All 40 endpoints with schemas
* [Use Cases Guide](https://docs.sorsa.io/use-cases-overview) - Real-world implementation patterns