Metadata-Version: 2.4
Name: socialapi-sdk
Version: 1.0.0
Summary: Real-time X (Twitter) data - 40 endpoints plus live streaming. $0.0008 per call, up to 30 tweets, from $0.000027 each. Around 100x cheaper than the official X API.
Author-email: SocialAPI Tech <contact@socialapi.tech>
Maintainer-email: SocialAPI Tech <contact@socialapi.tech>
License-Expression: MIT
Project-URL: Homepage, https://socialapi.tech
Project-URL: Documentation, https://socialapi.tech/docs
Project-URL: Repository, https://github.com/socialapitech/socialapi-python
Project-URL: Issues, https://github.com/socialapitech/socialapi-python/issues
Project-URL: Pricing, https://socialapi.tech/#pricing
Keywords: twitter,x,twitter-api,x-api,scraper,social-media,sentiment-analysis,twitter-data,api-client,socialapi,twitter-stream,realtime,websocket,twitter-monitoring
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: license-file

# SocialAPI — Python SDK

Real-time X (Twitter) data. **40 read endpoints** plus free account endpoints for checking your own balance and usage. Around 100× cheaper than the official X API.

```bash
pip install socialapi-sdk
```

```python
from socialapi import SocialAPI

api = SocialAPI("sk_your_key")          # or set SOCIALAPI_KEY

user = api.user_info(username="elonmusk")
print(user["followers_count"])

for t in api.user_last_tweets(username="elonmusk", limit=10):
    print(t["created_at"], t["text"][:80])
```

Get a key at **[socialapi.tech/signup](https://socialapi.tech/signup)** — no credit card.

---

## Why this exists

The official X API bills **per resource returned** — $0.005 a post, $0.010 a
profile. Pulling 30 posts costs $0.15 there; the same call here is $0.0008,
and a profile is $0.00015 instead of $0.010.

That gap is the whole reason this exists. Same pay-as-you-go model, roughly
100× less, one balance across every endpoint, and composite lookups plus
per-account streaming that the official API does not offer at all.

**Read-only by design.** There is no posting, liking, or following. That means
you never hand us an X account — a leaked key costs you some data queries, not
your voice.

---

## Common tasks

```python
# Search — full X syntax, real-time (not cached)
api.search_advanced(query="bitcoin min_faves:100", limit=30)

# Is this account alive, suspended, or gone?
api.user_status(username="someaccount")      # -> alive | suspended | not_found

# Followers / following with cursor pagination
page = api.user_followers(username="jack", limit=200)

# Trends — worldwide, or per-region with a WOEID
api.trends()
api.trends_place(woeid=1)

# One call, full picture (runs several lookups concurrently server-side)
api.user_whois(username="elonmusk")

# Batch profiles in one request
api.batch_user_info(usernames="elonmusk,jack,binance")

# Your own account — balance, spend, and what you're monitoring. These are free.
me = api.usage()                    # balance + today/month spend
api.analytics(days=14)              # per-endpoint usage + days of runway left
api.stream_subscriptions()          # which accounts you're watching, and the daily cost
```

Every method maps 1:1 to an endpoint in the
[API reference](https://socialapi.tech/docs).

---

## Watching accounts, not just querying them

The methods above are request-and-response: you ask, you get an answer. If what
you need is *"tell me the moment they post"*, that runs over a WebSocket or a
webhook instead — we push to you, median **two seconds** from post to delivery.

```python
# websockets, or any WS client
import json, websockets

url = "wss://api.socialapi.tech/v1/stream/ws?api_key=sk_your_key"
async with websockets.connect(url) as ws:
    async for msg in ws:
        tweet = json.loads(msg)
        print(tweet["user"], tweet["content"][:80])
```

Monitoring is **$0.08 per account per day**, billed hourly — stop it and the
billing stops. One account minimum, no bundles. It draws from the same balance
as everything else, so there's nothing extra to sign up for.

Setup and payload format: [socialapi.tech/docs](https://socialapi.tech/docs)

---

## What it costs

| | |
|---|---|
| A call returning up to 30 tweets | **$0.0008** |
| Per tweet, at 30 per call | **$0.000027** |
| Single profile lookup | **$0.00015** |
| Watching one account | **$0.08 / day** |

No monthly fee, no minimum, no card. Failed calls cost nothing, and credits
don't expire.

---

## Errors worth handling

```python
from socialapi import SocialAPI, RateLimited, InsufficientCredits, SocialAPIError

try:
    data = api.user_info(username="elonmusk")
except InsufficientCredits:
    ...   # 402 — top up. Do NOT retry; it will fail the same way.
except RateLimited:
    ...   # 429 — not charged. Back off and retry (the SDK already retries twice).
except SocialAPIError as e:
    print(e.status, e)
```

**402 and 429 mean different things.** 429 is "too fast, slow down" and costs
nothing. 402 is "out of balance" — retrying just burns time. The SDK retries
429 and 5xx automatically with exponential backoff, and never retries 402.

---

## Billing, briefly

- Only **successful** requests are charged.
- A call returning up to 30 items is **one tier** — asking for 30 costs the
  same as asking for 3, so request what you actually need.
- Every response carries an `x-credits-used` header.

Full rules: [socialapi.tech/#pricing](https://socialapi.tech/#pricing)

---

## Configuration

```python
api = SocialAPI(
    api_key="sk_...",       # or env SOCIALAPI_KEY
    base_url="https://api.socialapi.tech",
    timeout=30.0,           # seconds
    max_retries=2,          # for 429 / 5xx only
)

with SocialAPI() as api:    # context manager closes the session
    ...
```

---

## Support

- Docs — <https://socialapi.tech/docs>
- Telegram — <https://t.me/socialapi_support>
- Email — <contact@socialapi.tech>

MIT licensed.

> *SocialAPI is an independent service and is not affiliated with, endorsed by,
> or authorized by X Corp. "X" and "Twitter" are trademarks of X Corp., used
> here only to describe the data this service reads. We access only publicly
> visible data.*
