# Social Media API

> Pay-per-request social media data from 6 platforms. $0.06 per request (USDC on Base).

## How It Works: Async Two-Step Flow

Every data request follows a two-step pattern: **pay to trigger**, then **poll for free**.

### Step 1: POST to trigger (paid)

Send a POST request to any data endpoint with a payment header. Each call costs $0.06 in USDC on Base network.

On success you get back a **202 Accepted** with a signed JWT token:

```json
{ "token": "eyJhbGciOiJIUzI1NiIs..." }
```

The token is your receipt. It encodes everything needed to retrieve your data. No API keys, no sessions.

### Step 2: GET /api/jobs?token=... (free, no payment)

Poll this endpoint with your token. No payment required — the token IS your proof of payment.

**Pending** — data is still being collected, poll again in a few seconds:
```json
{ "status": "pending", "message": "Poll again in a few seconds." }
```

**Finished** — your data is ready:
```json
{ "status": "finished", "data": { ... } }
```

**Failed** — collection failed (you are NOT charged when the trigger itself fails):
```json
{ "status": "failed", "error": "..." }
```

### Complete Example

```
1. POST /api/x/profile  {"handle": "elonmusk"}
   → 202 {"token": "eyJ..."}

2. GET /api/jobs?token=eyJ...
   → 200 {"status": "pending", "message": "Poll again in a few seconds."}

3. GET /api/jobs?token=eyJ...  (a few seconds later)
   → 200 {"status": "finished", "data": {"username": "elonmusk", ...}}
```

### Token Details

- Tokens expire after **30 minutes** (jobs typically finish in 5–60 seconds)
- Tokens are replayable — you can poll as many times as needed, and re-fetch finished data
- If a token expires, make a new paid POST request
- Invalid or expired tokens return **401**

## Data Freshness & Dependencies

Data is fetched from social platforms on demand. To get complete results for dependent resources, update the base resource first:

**Example — fetching followers:**
1. `POST /api/x/profile` with `{"handle": "username"}` → get token, poll until finished
2. `POST /api/x/followers` with `{"handle": "username"}` → get token, poll until finished

**Example — fetching post replies:**
1. `POST /api/x/profile` → trigger profile collection
2. `POST /api/x/posts` → trigger post collection
3. `POST /api/x/post-replies` with post ID → get replies

### Pagination

After your first job finishes and returns data, use the `cursor` from `page_info` to fetch subsequent pages. Each page requires a new paid POST (which returns a new token to poll).

Continue paginating while `page_info.has_next_page` is `true`.

## Endpoints

All endpoints are POST requests that accept JSON bodies. All return 202 with a job token. All cost $0.06 per call.

| Endpoint | Free? | Description |
|---|---|---|
| **GET /api/jobs?token=...** | **Yes** | Poll job status and retrieve results |

### TikTok
| Endpoint | Price | Description | Depends on |
|---|---|---|---|
| POST /api/tiktok/profile | $0.06 | Get user profile | — |
| POST /api/tiktok/posts | $0.06 |Get user posts | profile |
| POST /api/tiktok/post-comments | $0.06 |Get video comments | posts |
| POST /api/tiktok/comment-replies | $0.06 |Get replies to a comment | post-comments |
| POST /api/tiktok/followers | $0.06 |Get followers | profile |
| POST /api/tiktok/following | $0.06 |Get following | profile |
| POST /api/tiktok/search | $0.06 |Search posts by keyword | — |
| POST /api/tiktok/search-hashtag | $0.06 |Search by hashtag | — |
| POST /api/tiktok/search-profiles | $0.06 |Search user profiles | — |
| POST /api/tiktok/search-music | $0.06 |Search posts by music/sound | — |

### Instagram
| Endpoint | Price | Description | Depends on |
|---|---|---|---|
| POST /api/instagram/profile | $0.06 | Get user profile | — |
| POST /api/instagram/posts | $0.06 |Get user posts | profile |
| POST /api/instagram/post-comments | $0.06 |Get post comments | posts |
| POST /api/instagram/comment-replies | $0.06 |Get replies to a comment | post-comments |
| POST /api/instagram/followers | $0.06 |Get followers | profile |
| POST /api/instagram/following | $0.06 |Get following | profile |
| POST /api/instagram/stories | $0.06 |Get user stories | profile |
| POST /api/instagram/highlights | $0.06 |Get user highlights | profile |
| POST /api/instagram/search | $0.06 |Search posts by keyword | — |
| POST /api/instagram/search-tags | $0.06 |Search by tag | — |

### X/Twitter
| Endpoint | Price | Description | Depends on |
|---|---|---|---|
| POST /api/x/profile | $0.06 | Get user profile | — |
| POST /api/x/posts | $0.06 |Get user posts/tweets | profile |
| POST /api/x/post-replies | $0.06 |Get replies to a post | posts |
| POST /api/x/post-retweets | $0.06 |Get retweet profiles | posts |
| POST /api/x/post-quotes | $0.06 |Get quote tweets | posts |
| POST /api/x/followers | $0.06 |Get followers | profile |
| POST /api/x/following | $0.06 |Get following | profile |
| POST /api/x/search | $0.06 |Search posts by keyword | — |
| POST /api/x/search-profiles | $0.06 |Search user profiles | — |

### Facebook
| Endpoint | Price | Description | Depends on |
|---|---|---|---|
| POST /api/facebook/profile | $0.06 | Get page/user profile | — |
| POST /api/facebook/posts | $0.06 |Get page/user posts | profile |
| POST /api/facebook/post-comments | $0.06 |Get post comments | posts |
| POST /api/facebook/comment-replies | $0.06 |Get replies to a comment | post-comments |
| POST /api/facebook/followers | $0.06 |Get followers | profile |
| POST /api/facebook/following | $0.06 |Get following | profile |
| POST /api/facebook/search | $0.06 |Search posts by keyword | — |
| POST /api/facebook/search-people | $0.06 |Search people profiles | — |
| POST /api/facebook/search-pages | $0.06 |Search page profiles | — |
| POST /api/facebook/search-groups | $0.06 |Search group profiles | — |

### Reddit
| Endpoint | Price | Description | Depends on |
|---|---|---|---|
| POST /api/reddit/post | $0.06 | Get post details | — |
| POST /api/reddit/post-comments | $0.06 |Get post comments | post |
| POST /api/reddit/comment | $0.06 | Get comment details | — |
| POST /api/reddit/search | $0.06 |Search posts by keyword | — |
| POST /api/reddit/search-profiles | $0.06 |Search user profiles | — |
| POST /api/reddit/subreddit | $0.06 |Get subreddit posts | — |

### LinkedIn
| Endpoint | Price | Description | Depends on |
|---|---|---|---|
| POST /api/linkedin/profile | $0.06 | Get member profile | — |
| POST /api/linkedin/posts | $0.06 |Get member activity posts | profile |
| POST /api/linkedin/company | $0.06 | Get company profile | — |
| POST /api/linkedin/company-posts | $0.06 |Get company feed posts | company |
| POST /api/linkedin/post-comments | $0.06 |Get post comments | posts |
| POST /api/linkedin/comment-replies | $0.06 |Get replies to a comment | post-comments |
| POST /api/linkedin/post-reactors | $0.06 |Get post reaction profiles | posts |
| POST /api/linkedin/search-posts | $0.06 |Search posts by keyword | — |
| POST /api/linkedin/search-jobs | $0.06 |Search job postings | — |
| POST /api/linkedin/search-members | $0.06 |Search member profiles | — |
| POST /api/linkedin/search-companies | $0.06 |Search company profiles | — |
| POST /api/linkedin/search-ads | $0.06 |Search ad posts by company | — |

## Key Parameters

- **handle** / **profile_id** / **member_id** / **company_id**: Username or ID of the target account
- **max_page_size**: Results per page (default varies, max 100)
- **max_followers**: How many followers to collect (default 500)
- **max_posts** / **max_activities** / **max_results**: How many items to collect (default 50)
- **cursor**: Pagination cursor from previous response
- **order_by**: Sort order (date_desc, date_asc, id_desc)
- **activity_type**: LinkedIn activity type (posts, articles, documents, media, comments)
- **reaction_type**: LinkedIn reaction type (LIKE, CELEBRATE, SUPPORT, LOVE, INSIGHTFUL, FUNNY)

## Error Handling

- **400** — Bad request (missing/invalid parameters)
- **401** — Invalid or expired job token (on /api/jobs)
- **402** — Payment required (payment header missing or invalid)
- **502** — Upstream data collection failed

If the POST trigger itself fails (bad params, entity not found), you get an immediate error and are NOT charged — payment only settles on 2xx responses.

## Authentication

No API keys needed. Payment via USDC on Base network serves as authentication. The job token returned by the paid POST is your proof of payment for polling.

## OpenAPI Spec

Full schema available at `/openapi.json`