# API Direct - Complete Documentation
> API Direct is a pay-as-you-go API for social media and news. Search real-time data across LinkedIn, Twitter/X, Reddit, YouTube, Instagram, TikTok, Facebook, web forums, and news articles through a unified REST API.
Base URL: https://apidirect.io
Authentication: X-API-Key header
---
# Introduction
API Direct is a pay-as-you-go API that lets you search real-time data across social media and news through a single, unified interface.
## Supported Platforms
- **LinkedIn** - Search posts and articles
- **Twitter / X** - Search tweets and threads
- **Facebook** - Pages, groups, posts, photos, videos, reels, and reviews
- **Reddit** - Search posts and comments
- **YouTube** - Search videos with date filters
- **Instagram** - Search posts by hashtag
- **TikTok** - Search videos with engagement metrics
- **Web Search** - Real-time Google organic search results with country, language, and geo targeting
- **Google AI Mode** - Send a prompt to Google's AI Mode and get a Markdown-formatted answer with citations
- **Forums** - Search discussion boards and Q&A sites across the web
- **News** - Search news articles from thousands of sources worldwide
## Base URL
All API requests are made to:
```
https://apidirect.io
```
## Key Features
**Unified response format** - Every endpoint returns the same core fields: `title`, `url`, `date`, `author`, `source`, `domain`, and `snippet`. This makes it easy to work with data from multiple platforms without writing platform-specific parsing logic.
**Pay per request** - No monthly subscriptions or commitments. You only pay for successful API calls, with prices starting at $0.002 per request.
**Free tier** - Every account gets 50 free requests per endpoint per month. No credit card required to get started.
**Real-time data** - Results are fetched in real-time when you make a request. Access posts from the last few seconds to several years ago.
**Simple authentication** - Authenticate with a single API key passed in the `X-API-Key` header.
## Next Steps
- Follow the [Quickstart](/docs/quickstart) guide to make your first API call
- Learn about [Authentication](/docs/authentication)
- Browse the [endpoint documentation](/docs/linkedin-posts) for detailed parameter and response references
---
# Quickstart
Get up and running with API Direct in three steps.
## Step 1: Create an Account
Sign up at [apidirect.io/signup](https://apidirect.io/signup). No credit card required — you get 50 free requests per endpoint every month.
## Step 2: Create an API Key
After signing in, go to the [API Keys](https://apidirect.io/dashboard/keys) page in your dashboard and create a new key. Your key will look like `ak_live_...`. Copy it — you'll need it for the next step.
## Step 3: Make Your First Request
### Using cURL
```bash
curl "https://apidirect.io/v1/reddit/posts?query=programming&page=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Using Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/reddit/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "programming",
"page": 1
}
)
data = response.json()
for post in data["posts"]:
print(post["title"], "-", post["url"])
```
### Example Response
```json
{
"posts": [
{
"title": "Best resources for learning programming",
"url": "https://reddit.com/r/learnprogramming/...",
"date": "2024-06-15 10:30:00",
"author": "dev_learner",
"source": "Reddit",
"domain": "reddit.com",
"subreddit": "learnprogramming",
"snippet": "I've compiled a list of the best free resources..."
}
],
"page": 1,
"count": 20
}
```
## What's Next
- Learn about [Authentication](/docs/authentication) and managing API keys
- Understand the [Response Format](/docs/response-format) shared across all endpoints
- Browse the full [endpoint reference](/docs/linkedin-posts)
---
# Authentication
All API requests require authentication using an API key passed in the `X-API-Key` header.
## The X-API-Key Header
Include your API key in every request:
```bash
curl "https://apidirect.io/v1/reddit/posts?query=test" \
-H "X-API-Key: ak_live_abc123..."
```
```python
import requests
response = requests.get(
"https://apidirect.io/v1/reddit/posts",
headers={"X-API-Key": "ak_live_abc123..."},
params={"query": "test"}
)
```
## Key Format
API keys follow the format `ak_live_` followed by a random string. For example:
```
ak_live_7f3a9b2c1d4e5f6a8b9c0d1e2f3a4b5c
```
## Managing Keys
You can create and manage API keys from your [dashboard](https://apidirect.io/dashboard/keys):
- **Create** up to 10 keys per account
- **Revoke** a key to immediately disable it (can be re-enabled later)
- **Delete** a key to permanently remove it
See [API Keys](/docs/api-keys) for more details on key management.
## Error Responses
If authentication fails, you'll receive one of these responses:
**Missing API key** (no header provided):
```json
{
"error": "Missing API key",
"code": "missing_api_key"
}
```
Status: `401`
**Invalid API key** (key not found or deleted):
```json
{
"error": "Invalid API key",
"code": "invalid_api_key"
}
```
Status: `401`
**Account blocked** (payment failure):
```json
{
"error": "Account blocked due to payment failure. Please update your payment method.",
"code": "account_blocked"
}
```
Status: `403`
---
# Response Format
All endpoints return a consistent JSON structure, making it easy to work with data from multiple platforms using the same code.
## Standard Response Shape
```json
{
"posts": [
{
"title": "Post title or heading",
"url": "https://platform.com/post/...",
"date": "2024-06-15 14:30:00",
"author": "username",
"source": "Platform Name",
"domain": "platform.com",
"snippet": "Content preview or excerpt..."
}
],
"page": 1,
"count": 20
}
```
## Core Fields
Most post objects contain these fields:
| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Post title or formatted heading |
| `url` | string | Direct link to the original post |
| `date` | string | Publication date (`YYYY-MM-DD HH:MM:SS`). Not returned by Forum Posts, News Articles, or Web Search. |
| `author` | string | Author name or username. Not returned by Forum Posts, News Articles, or Web Search (News uses `authors` array). |
| `source` | string | Platform name (e.g., "Reddit", "LinkedIn") |
| `domain` | string | Platform domain (e.g., "reddit.com", "linkedin.com") |
| `snippet` | string | Content text or preview |
## Pagination Fields
Depending on the endpoint, responses include either `page` (current page number) or `pages` (number of pages fetched), plus a `count` of total results returned.
| Field | Type | Description |
|-------|------|-------------|
| `page` | integer | Current page number (used by LinkedIn, Reddit Posts, Forum Posts) |
| `pages` | integer | Number of pages fetched (used by Twitter, Reddit Comments, YouTube, Instagram, TikTok, Web Search) |
| `limit` | integer | Requested result limit (used by News Articles) |
| `count` | integer | Total number of results returned |
## Platform-Specific Fields
Many endpoints include additional fields beyond the core set above. Common examples:
| Field | Description |
|-------|-------------|
| `likes` | Number of likes (LinkedIn, Twitter, Instagram, TikTok) |
| `views` | Number of views (Twitter, YouTube, Instagram) |
| `comments` | Number of comments (LinkedIn, Instagram, TikTok) |
| `shares` | Number of shares (LinkedIn, Instagram, TikTok) |
| `hashtags` | Hashtags used in the post (Twitter, Instagram) |
| `subreddit` | Subreddit name (Reddit) |
| `thumbnail` | Thumbnail URL (YouTube, TikTok) |
| `reactions_count` | Number of reactions (Facebook) |
| `cursor` | Pagination cursor for next page (Facebook, Twitter) |
Each endpoint's documentation page includes the full list of fields returned. See the [endpoint docs](/docs/linkedin-posts) for complete response schemas.
## Full Example
```json
{
"posts": [
{
"title": "Best practices for API design",
"url": "https://reddit.com/r/programming/comments/abc123",
"date": "2024-06-15 14:30:00",
"author": "dev_user",
"source": "Reddit",
"domain": "reddit.com",
"subreddit": "programming",
"snippet": "After building dozens of APIs, here are the patterns that work best..."
},
{
"title": "Why REST still matters in 2024",
"url": "https://reddit.com/r/webdev/comments/def456",
"date": "2024-06-14 09:15:00",
"author": "web_architect",
"source": "Reddit",
"domain": "reddit.com",
"subreddit": "webdev",
"snippet": "Despite the rise of GraphQL, REST APIs continue to be the standard..."
}
],
"page": 1,
"count": 20
}
```
---
# Boolean Search
Your `query` is passed straight through to each platform's own search engine, so on supported endpoints you can use that platform's boolean operators — exact phrases (`"..."`), `OR`, exclusion (`-term`), and grouping `( )` — to build precise queries.
Operators like `OR`, `AND`, and `NOT` must be **UPPERCASE**; lowercase is treated as an ordinary search word.
## Endpoints that support boolean operators
| Endpoint | Operator reference |
|----------|--------------------|
| `/v1/reddit/posts` | [Reddit search operators](https://support.reddithelp.com/hc/en-us/articles/19696541895316-Available-search-features) — `AND` `OR` `NOT` `-` `( )`, fields like `subreddit:` `author:` |
| `/v1/twitter/posts` | [X advanced search](https://help.x.com/en/using-x/x-advanced-search) — phrases, `OR`, `-`, `( )`, fields like `from:` `filter:` (use `-`, not `NOT`) |
| `/v1/forums/posts` | [Google search operators](https://support.google.com/websearch/answer/2466433) — phrases, `OR`/`\|`, `-`, `( )`, `site:` (use `-`, not `NOT`) |
| `/v1/linkedin/posts` | [LinkedIn boolean search](https://www.linkedin.com/help/linkedin/answer/a524335) — `AND` `OR` `NOT` `-` `( )` (phrases are matched loosely) |
```bash
curl -G "https://apidirect.io/v1/reddit/posts" \
--data-urlencode 'query=(remote OR hybrid) engineer -recruiter' \
-H "X-API-Key: YOUR_API_KEY"
```
## Everything else is keyword search
`/v1/youtube/posts`, `/v1/facebook/posts`, `/v1/instagram/posts`, and `/v1/tiktok/videos` don't support operators — they run relevance-based keyword search, so any operator you include is treated as literal text. Pass plain keywords instead. (On YouTube and Facebook every word must appear; Instagram and TikTok match loosely.)
---
# Pagination
API Direct endpoints support pagination to retrieve multiple pages of results. There are two pagination patterns depending on the endpoint.
## Pattern 1: `page` Parameter
Some endpoints use a `page` parameter where you request one page at a time. Each request returns a single page of results.
**Endpoints using `page`:** LinkedIn Posts, Reddit Posts, Forum Posts
```bash
# Get page 1
curl "https://apidirect.io/v1/reddit/posts?query=python&page=1" \
-H "X-API-Key: YOUR_API_KEY"
# Get page 2
curl "https://apidirect.io/v1/reddit/posts?query=python&page=2" \
-H "X-API-Key: YOUR_API_KEY"
```
The response includes the current `page` number:
```json
{
"posts": [...],
"page": 2,
"count": 20
}
```
## Pattern 2: `pages` Parameter
Other endpoints use a `pages` parameter that fetches multiple pages in a single API call. This is useful for retrieving larger result sets without making multiple requests.
**Endpoints using `pages`:** Twitter Posts, Facebook (all paginated endpoints), Reddit Comments, YouTube Videos, Instagram Posts, TikTok Videos, Web Search
```bash
# Fetch 3 pages of results in one call
curl "https://apidirect.io/v1/twitter/posts?query=AI&pages=3" \
-H "X-API-Key: YOUR_API_KEY"
```
The response includes the number of `pages` fetched:
```json
{
"posts": [...],
"pages": 3,
"count": 60
}
```
## Page Limits
| Endpoint | Param | Max Pages |
|----------|-------|-----------|
| LinkedIn Posts | `page` | Not specified |
| Reddit Posts | `page` | 5 |
| Forum Posts | `page` | Not specified |
| Twitter Posts | `pages` | 10 |
| Twitter User Following | `pages` | 175 |
| Facebook (paginated) | `pages` | 10 |
| Reddit Comments | `pages` | 5 |
| YouTube Videos | `pages` | 10 |
| Instagram Posts | `pages` | 10 |
| TikTok Videos | `pages` | 10 |
| Web Search | `pages` | 10 |
## Pattern 3: `limit` Parameter
The News Articles endpoint uses a `limit` parameter to control how many results are returned per request (1-100, default 10). Unlike `page` or `pages`, this is not paginated — you get up to `limit` results in a single call.
**Endpoints using `limit`:** News Articles
```bash
# Get 50 news articles
curl "https://apidirect.io/v1/news/articles?query=technology&limit=50" \
-H "X-API-Key: YOUR_API_KEY"
```
The response includes the requested `limit` and actual `count`:
```json
{
"articles": [...],
"limit": 50,
"count": 50
}
```
## Billing Note
For endpoints using the `pages` parameter, you are billed per page fetched. For example, requesting `pages=3` on the Twitter endpoint costs 3x the per-page price.
The News Articles endpoint is billed as a single request regardless of the `limit` value.
---
# Batch Requests
Instead of looping an endpoint over a list of IDs, URLs or usernames, send up to 100 requests in a single call:
```
POST /v1/batch
```
Any mix of endpoints is allowed. Items run concurrently server-side (up to roughly half your per-endpoint concurrency limit at a time; the rest queue) and each returns its own status and body, in input order.
Batching is free — each item bills under its own endpoint at its normal rate, and consumes that endpoint's free tier, exactly as a direct call. Available over MCP as the `batch_requests` tool.
## Request Body
JSON object with a `requests` array of 1–100 items.
| Field | Required | Description |
|-----------|----------|-------------|
| `requests` | Yes | Array of 1–100 items to execute |
| `requests[].endpoint` | Yes | The `/v1` endpoint path to call (e.g. `/v1/twitter/user`). Every endpoint is supported except `/v1/web/ai-mode` |
| `requests[].params` | No | The same parameters the endpoint accepts when called directly. Values must be strings or numbers |
| `requests[].tag` | No | Optional label (max 100 characters) echoed back on the item's result |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `results` | array | Per-item results, in input order |
| `results[].index` | integer | Position of the item in the `requests` array |
| `results[].endpoint` | string | The endpoint the item called |
| `results[].tag` | string | The item's tag (when one was sent) |
| `results[].status` | integer | The item's HTTP status: 200 success; 4xx/5xx the endpoint's normal error; 0 the item was not attempted (failed, never billed) |
| `results[].body` | object | Exactly what the endpoint returns when called directly |
| `summary.total` | integer | Number of items in the batch |
| `summary.succeeded` | integer | Items that returned 2xx |
| `summary.failed` | integer | Items that did not succeed (failed items are never billed) |
| `summary.duration_ms` | integer | Total batch execution time |
## Example Request
### cURL
```bash
curl -X POST "https://apidirect.io/v1/batch" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"requests": [
{"endpoint": "/v1/twitter/user", "params": {"username": "naval"}},
{"endpoint": "/v1/twitter/user", "params": {"username": "paulg"}},
{"endpoint": "/v1/instagram/user", "params": {"username": "instagram"}}
]}'
```
### Python
```python
import requests
response = requests.post(
"https://apidirect.io/v1/batch",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"requests": [
{"endpoint": "/v1/twitter/user", "params": {"username": "naval"}},
{"endpoint": "/v1/twitter/user", "params": {"username": "paulg"}},
{"endpoint": "/v1/instagram/user", "params": {"username": "instagram"}},
]},
timeout=780,
)
for item in response.json()["results"]:
print(item["endpoint"], item["status"])
```
## Example Response
```json
{
"results": [
{
"index": 0,
"endpoint": "/v1/twitter/user",
"status": 200,
"body": {
"user": {
"name": "Naval",
"username": "naval",
"followers": 2100000
}
}
},
{
"index": 1,
"endpoint": "/v1/twitter/user",
"status": 200,
"body": { "user": { "name": "Paul Graham", "username": "paulg" } }
},
{
"index": 2,
"endpoint": "/v1/instagram/user",
"status": 200,
"body": { "user": { "username": "instagram" } }
}
],
"summary": {
"total": 3,
"succeeded": 3,
"failed": 0,
"duration_ms": 4200
}
}
```
## Notes
- **Billing** — batching is free. Each item bills exactly like a direct call: same price, same free tier, same spending limits. Failed items are never billed.
- **Concurrency** — items run in parallel at up to roughly half your per-endpoint concurrency limit; the rest queue and start as slots free.
- **Isolation** — one item failing never affects the others. Each result is exactly what its endpoint would return directly, and rate-limited items are retried automatically.
- **Failed items** — any item that fails, including items the batch could not get to, returns an error body with a `code` and is never billed.
---
# Error Handling
When a request fails, API Direct returns a JSON error response with an HTTP status code, an `error` message, and a `code` identifier.
## Error Response Format
```json
{
"error": "Human-readable error message",
"code": "machine_readable_code"
}
```
## Error Codes
| Status | Code | Description |
|--------|------|-------------|
| `400` | `missing_parameter` | A required parameter (e.g., `query`) was not provided |
| `400` | `invalid_parameter` | A parameter value is invalid (too long, wrong format, etc.) |
| `401` | `missing_api_key` | No `X-API-Key` header was provided |
| `401` | `invalid_api_key` | The API key is invalid, revoked, or deleted |
| `401` | `user_not_found` | The user account associated with the key was not found |
| `402` | `payment_required` | Free tier limit reached for this endpoint and no payment method on file |
| `403` | `account_blocked` | Account blocked due to payment failure |
| `429` | `daily_limit_exceeded` | Daily spending limit reached |
| `429` | `monthly_limit_exceeded` | Monthly spending limit reached |
| `429` | `concurrency_limit_exceeded` | Too many concurrent requests to this endpoint |
| `429` | `upstream_rate_limit` | The upstream data source is rate-limiting requests |
| `502` | `upstream_error` | The data source returned an error |
| `502` | `upstream_connection_error` | Could not connect to the upstream data source |
| `503` | `service_error` | Service configuration error |
| `503` | `upstream_auth_error` | Authentication with the upstream data source failed |
| `500` | `auth_error` | An error occurred during API key validation |
| `500` | `billing_error` | Billing configuration or processing error |
| `504` | `upstream_timeout` | The data source did not respond in time |
## Handling Errors
### Authentication Errors (401)
Check that you're including the `X-API-Key` header and that your key is valid and active. You can verify your keys in the [dashboard](https://apidirect.io/dashboard/keys).
### Payment Errors (402, 403)
A `402` means your free tier is exhausted and you need to add a payment method. A `403` with `account_blocked` means a previous payment failed — update your card in the [billing dashboard](https://apidirect.io/dashboard/billing).
### Rate Limits and Spending Limits (429)
A `429` with `concurrency_limit_exceeded` means you have too many in-flight requests to the same endpoint. Wait for current requests to complete. See [Rate Limits](/docs/rate-limits) for details.
A `429` with `daily_limit_exceeded` or `monthly_limit_exceeded` means you've hit a spending cap. See [Spending Limits](/docs/spending-limits).
### Parameter Errors (400)
A `400` with `missing_parameter` means you forgot a required parameter (e.g., `query`). A `400` with `invalid_parameter` means a parameter value is invalid — check the endpoint documentation for allowed values and limits.
### Upstream Errors (502, 503, 504)
These indicate a temporary issue with the data source. A `503` with `service_error` or `upstream_auth_error` typically resolves on its own. Retry after a short delay (1-2 seconds). If the error persists, the platform may be experiencing an outage.
## Retry Strategy
For transient errors (`502`, `504`, `429` with `concurrency_limit_exceeded` or `upstream_rate_limit`), we recommend:
1. Wait 1-2 seconds before retrying
2. Use exponential backoff for repeated failures
3. Set a maximum of 3 retries per request
---
# Rate Limits
API Direct enforces concurrency limits to ensure fair usage and reliable performance for all users.
## Concurrency Limit
Each user is limited to **5 concurrent requests per endpoint**. This means you can have up to 5 in-flight requests to the same endpoint at the same time. Requests to different endpoints are counted separately.
For example, you can simultaneously make:
- 5 requests to `/v1/reddit/posts`
- 5 requests to `/v1/twitter/posts`
- 5 requests to `/v1/linkedin/posts`
## 429 Response
If you exceed the concurrency limit, you'll receive a `429` status code:
```json
{
"error": "Too many concurrent requests for this endpoint. If you need higher concurrency limits, contact support@apidirect.io",
"code": "concurrency_limit_exceeded",
"limit": 5,
"current": 5
}
```
## Best Practices
**Use sequential requests** - For most use cases, sending requests one at a time is sufficient given the 1-2 second response times.
**Queue your requests** - If you need to make many requests, implement a queue that limits concurrency to 5 per endpoint.
**Use the `pages` parameter** - Endpoints like Twitter, YouTube, Instagram, and TikTok support fetching multiple pages in a single request, reducing the total number of API calls needed.
**Spread across endpoints** - Concurrency limits are per-endpoint, so requests to different endpoints don't count against each other.
## Need Higher Limits?
If you need higher concurrency limits for your use case, contact us at [support@apidirect.io](mailto:support@apidirect.io).
---
# LinkedIn Posts
Search LinkedIn posts and articles by keyword. Returns post content, author, publication date, engagement metrics (likes, comments, shares, reactions), and attached content (images, articles, videos, job listings) for each result.
## Endpoint
```
GET /v1/linkedin/posts
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Conditional | Search keyword (max 500 characters). Required unless at least one filter (e.g. `author`) is provided. |
| `page` | No | Page number for pagination (default: 1) |
| `sort_by` | No | Sort order: `most_recent` or `relevance` (default: `most_recent`) |
| `author` | No | Filter to posts authored by a specific person. Accepts a profile URL, public slug (e.g. `williamhgates`), or member URN — resolved automatically. Comma-separate for multiple. |
| `mentions_member` | No | Filter to posts that mention a specific person (profile URL, slug, or member URN). |
| `from_company` | No | Filter to posts authored by a company page. Numeric LinkedIn company ID (get it from the [Company Details](/docs/linkedin-company) endpoint). Comma-separate for multiple. |
| `author_company` | No | Filter to posts written by people who work at a company. Numeric company ID. |
| `mentions_company` | No | Filter to posts that mention a company. Numeric company ID. |
| `author_title` | No | Filter by the author's job title as free text (e.g. `CEO`). |
| `author_industry` | No | Filter by the author's industry. Numeric LinkedIn industry ID(s), comma-separated. Advanced. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching posts |
| `posts[].title` | string | Post title (format: `@author on LinkedIn`) |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Author name |
| `posts[].source` | string | `"LinkedIn"` |
| `posts[].domain` | string | `"linkedin.com"` |
| `posts[].snippet` | string | Post content text |
| `posts[].urn` | string | LinkedIn post URN identifier |
| `posts[].likes` | integer | Number of likes |
| `posts[].comments` | integer | Number of comments |
| `posts[].shares` | integer | Number of shares |
| `posts[].reactions` | object | Reaction type breakdown (e.g. `{"like": 2, "appreciation": 1}`) |
| `posts[].images` | array | Image URLs attached to the post |
| `posts[].article` | object/null | Shared article with `title`, `subtitle`, `url`, `description` |
| `posts[].video` | object/null | Video content with `thumbnail` and `duration` (ms) |
| `posts[].job` | object/null | Job listing with `title`, `subtitle`, `url`, `description` |
| `posts[].has_content_entities` | boolean | `true` if the post has attached content (image, article, video, or job). Posts with `has_content_entities: false` may be reposts — use the Post Details endpoint to check. |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `page` | integer | Current page number |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/posts?query=artificial%20intelligence&page=1&sort_by=most_recent" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "artificial intelligence",
"page": 1,
"sort_by": "most_recent"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@John Doe on LinkedIn",
"url": "https://linkedin.com/posts/...",
"date": "2024-01-15 14:30:00",
"author": "John Doe",
"source": "LinkedIn",
"domain": "linkedin.com",
"snippet": "Exciting developments in artificial intelligence...",
"urn": "urn:li:activity:7444854690124652545",
"likes": 12,
"comments": 3,
"shares": 1,
"reactions": {
"like": 10,
"appreciation": 2
},
"images": [
"https://media.licdn.com/dms/image/..."
],
"article": null,
"video": null,
"job": null,
"has_content_entities": true,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"page": 1,
"count": 10
}
```
---
# LinkedIn Person Posts
Get the recent posts authored by a LinkedIn person (their profile feed) by profile URL or public slug. Returns post content, engagement metrics (likes, comments, shares, reaction breakdowns), author info, images, videos, and articles.
## Endpoint
```
GET /v1/linkedin/person/posts
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | LinkedIn profile URL or public slug — e.g. `https://www.linkedin.com/in/williamhgates` or just `williamhgates` (max 500 characters) |
| `page` | No | Page number, 1-5 (default: 1). 20 posts per page — returns up to ~100 of the person's most recent posts. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of the person's posts |
| `posts[].url` | string | Post URL |
| `posts[].text` | string | Full post text content |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Author name |
| `posts[].author_description` | string | Author headline (e.g. job title or follower count) |
| `posts[].author_image` | string | Author profile image URL |
| `posts[].author_url` | string | Author profile URL |
| `posts[].likes` | integer | Total number of reactions |
| `posts[].comments` | integer | Number of comments |
| `posts[].shares` | integer | Number of reposts/shares |
| `posts[].reactions` | object | Breakdown of reaction types and counts |
| `posts[].is_repost` | boolean | Whether the post is a repost or quote-reshare |
| `posts[].images` | array | Array of image URLs |
| `posts[].video` | object/null | Video content with `thumbnail` and `duration` (ms) |
| `posts[].article` | object/null | Shared article with `title`, `subtitle`, `url`, `description` |
| `posts[].urn` | string | LinkedIn post URN identifier |
| `posts[].source` | string | `"LinkedIn"` |
| `posts[].domain` | string | `"linkedin.com"` |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `page` | integer | Current page number |
| `count` | integer | Number of posts returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/person/posts?url=williamhgates&page=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/person/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"url": "williamhgates",
"page": 1
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"url": "https://www.linkedin.com/posts/williamhgates_activity-7474530647273934848-VLxg",
"text": "I got involved in global health back in 1997...",
"date": "2026-06-21 18:36:16",
"author": "Bill Gates",
"author_description": "Chair, Gates Foundation and Founder, Breakthrough Energy",
"author_image": "https://media.licdn.com/dms/image/...",
"author_url": "https://www.linkedin.com/in/williamhgates",
"likes": 3706,
"comments": 368,
"shares": 28,
"reactions": {
"like": 3290,
"appreciation": 145,
"empathy": 168
},
"is_repost": false,
"images": [],
"video": {
"thumbnail": "https://media.licdn.com/dms/image/...",
"duration": 83600
},
"article": null,
"urn": "urn:li:activity:7474530647273934848"
}
],
"page": 1,
"count": 20
}
```
---
# LinkedIn Post Details
Get detailed information about a specific LinkedIn post including engagement metrics (likes, comments, shares), author details, images, and embedded links.
## Endpoint
```
GET /v1/linkedin/post
```
**Price:** $0.002 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | LinkedIn post URL (max 500 characters) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Canonical post URL |
| `text` | string | Full post text content |
| `date` | string | Publication date and time |
| `author` | string | Author name |
| `author_description` | string | Author description (e.g. follower count) |
| `author_image` | string | Author profile image URL |
| `author_url` | string | Author profile URL |
| `likes` | integer | Number of likes |
| `comments` | integer | Number of comments |
| `shares` | integer | Number of shares |
| `reactions` | object | Breakdown of reaction types and counts |
| `is_repost` | boolean | Whether the post is a repost |
| `images` | array | Array of image URLs attached to the post |
| `links` | array | Links embedded in the post |
| `urn` | string | LinkedIn URN identifier |
| `source` | string | `"LinkedIn"` |
| `domain` | string | `"linkedin.com"` |
| `sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/post?url=https://www.linkedin.com/feed/update/urn:li:activity:7219434359085252608" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/post",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"url": "https://www.linkedin.com/feed/update/urn:li:activity:7219434359085252608"
}
)
print(response.json())
```
## Example Response
```json
{
"url": "https://www.linkedin.com/feed/update/urn:li:activity:7219434359085252608",
"text": "Excited to share our latest project on AI...",
"date": "2024-07-15 10:30:00",
"author": "Jane Smith",
"author_description": "1,234 followers",
"author_image": "https://media.licdn.com/...",
"author_url": "https://www.linkedin.com/in/janesmith/",
"likes": 142,
"comments": 23,
"shares": 8,
"reactions": {
"like": 100,
"celebrate": 25,
"support": 17
},
"is_repost": false,
"images": [
"https://media.licdn.com/..."
],
"links": [],
"urn": "urn:li:activity:7219434359085252608",
"source": "LinkedIn",
"domain": "linkedin.com",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
```
---
# LinkedIn Company Details
Get detailed information about a LinkedIn company page by URL. Returns company name, description, employee count, locations, specialities, website, industry, headquarters, similar companies, and more.
## Endpoint
```
GET /v1/linkedin/company
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | LinkedIn company page URL (max 500 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Company name |
| `company_id` | integer | LinkedIn company ID |
| `url` | string | Company page URL |
| `universal_name` | string | URL-friendly company identifier |
| `description` | string | Company description |
| `tagline` | string | Company tagline |
| `website` | string | Company website URL |
| `industry` | string | Industry category |
| `followers` | integer | Number of LinkedIn followers |
| `employees` | integer | Employee count |
| `employee_range` | string | Employee count range (e.g. "201-500") |
| `founded_year` | integer | Year the company was founded |
| `hashtag` | string | Company hashtag |
| `specialities` | array | Array of company specialities/skills |
| `headquarters` | object | Headquarters location (city, country, region, postal_code, address) |
| `locations` | array | Array of all office locations |
| `logo` | string | Company logo image URL |
| `cover_image` | string | Company cover image URL |
| `call_to_action` | object | Call-to-action button (text, url) |
| `similar_companies` | array | Array of similar companies (name, url, industry, followers, logo) |
| `showcases` | array | Array of affiliated showcase pages (name, url, followers) |
| `source` | string | `"LinkedIn"` |
| `domain` | string | `"linkedin.com"` |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/company?url=https://www.linkedin.com/company/visualsoft-uk-ltd" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/company",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"url": "https://www.linkedin.com/company/visualsoft-uk-ltd"
}
)
print(response.json())
```
## Example Response
```json
{
"name": "Visualsoft | Shopify Plus Partner | Full Service Agency",
"company_id": 478635,
"url": "https://www.linkedin.com/company/visualsoft-uk-ltd/",
"universal_name": "visualsoft-uk-ltd",
"description": "We deliver the Shopify stores, in-store tech...",
"tagline": "We deliver the Shopify stores...",
"website": "http://www.visualsoft.co.uk",
"industry": "Software Development",
"followers": 16391,
"employees": 269,
"employee_range": "201-500",
"founded_year": 1998,
"hashtag": "#digitalmarketing",
"specialities": ["eCommerce", "Web Design", "SEO", "PPC"],
"headquarters": {
"city": "Stockton-on-Tees",
"country": "GB",
"region": "Cleveland",
"postal_code": "TS17 6QY",
"address": "Visualsoft House"
},
"locations": [
{
"city": "Newcastle upon Tyne",
"country": "GB",
"region": "England",
"postal_code": "NE1 6EF",
"address": "71 Grey Street",
"description": "Newcastle Office",
"is_headquarters": false
}
],
"logo": "https://media.licdn.com/...",
"cover_image": "https://media.licdn.com/...",
"call_to_action": {
"text": "Visit website",
"url": "http://www.visualsoft.co.uk"
},
"similar_companies": [
{
"name": "Shopify",
"url": "https://www.linkedin.com/company/shopify/",
"industry": "Software Development",
"followers": 1067167,
"logo": "https://media.licdn.com/..."
}
],
"showcases": [
{
"name": "Visualsoft SEO",
"url": "https://www.linkedin.com/showcase/visualsoft-seo/",
"followers": 63
}
],
"source": "LinkedIn",
"domain": "linkedin.com"
}
```
---
# LinkedIn Company Posts
Get recent posts from a LinkedIn company page by URL. Returns post content, engagement metrics (likes, comments, shares, reaction breakdowns), author info, images, videos, and pagination info.
## Endpoint
```
GET /v1/linkedin/company/posts
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | LinkedIn company page URL (max 500 characters) |
| `page` | No | Page number for pagination (default: 1) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of company posts |
| `posts[].url` | string | Post URL |
| `posts[].text` | string | Full post text content |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Author name |
| `posts[].author_description` | string | Author description |
| `posts[].author_image` | string | Author profile image URL |
| `posts[].author_url` | string | Author profile URL |
| `posts[].likes` | integer | Number of likes |
| `posts[].comments` | integer | Number of comments |
| `posts[].shares` | integer | Number of shares |
| `posts[].reactions` | object | Breakdown of reaction types and counts |
| `posts[].is_repost` | boolean | Whether the post is a repost |
| `posts[].images` | array | Array of image URLs |
| `posts[].video` | object | Video data (thumbnail, duration) or null |
| `posts[].links` | array | Links embedded in the post |
| `posts[].urn` | string | LinkedIn URN identifier |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `page` | integer | Current page number |
| `count` | integer | Number of posts returned |
| `total` | integer | Total number of posts available |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/company/posts?url=https://www.linkedin.com/company/visualsoft-uk-ltd&page=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/company/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"url": "https://www.linkedin.com/company/visualsoft-uk-ltd",
"page": 1
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"url": "https://www.linkedin.com/feed/update/urn:li:activity:7437505720176144385",
"text": "Exciting news from our team...",
"date": "2024-03-11 14:32:25",
"author": "Visualsoft | Shopify Plus Partner",
"author_description": "16,391 followers",
"author_image": "https://media.licdn.com/...",
"author_url": "https://www.linkedin.com/company/visualsoft-uk-ltd/posts",
"likes": 13,
"comments": 0,
"shares": 5,
"reactions": {
"like": 10,
"empathy": 3
},
"is_repost": false,
"images": [],
"video": {
"thumbnail": "https://media.licdn.com/...",
"duration": 102166
},
"links": ["https://www.linkedin.com/company/sportsshoes-com/"],
"urn": "urn:li:activity:7437505720176144385",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"page": 1,
"count": 10,
"total": 462
}
```
---
# LinkedIn Companies
Search LinkedIn companies by keyword. Returns company name, description, industry, location, follower count, logo, and direct link. Supports pagination with 10 results per page.
## Endpoint
```
GET /v1/linkedin/companies
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `page` | No | Page number, 1-100 (default: 1). Each page returns 10 results. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `companies` | array | Array of matching companies |
| `companies[].name` | string | Company name |
| `companies[].company_id` | string | LinkedIn company ID |
| `companies[].description` | string | Company summary / tagline |
| `companies[].subtitle` | string | Industry and location (e.g., "Software Development - San Francisco") |
| `companies[].followers` | string | Follower count (e.g., "2M followers") |
| `companies[].logo` | string | URL to company logo |
| `companies[].url` | string | Link to the LinkedIn company page |
| `page` | integer | Current page number |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/companies?query=AI&page=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/companies",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"query": "AI", "page": 1}
)
print(response.json())
```
## Example Response
```json
{
"companies": [
{
"name": "AI For Enterprise",
"company_id": "69206356",
"description": "Become better at AI in just 1 minute a day.",
"subtitle": "Business Content - San Francisco",
"followers": "2M followers",
"logo": "https://media.licdn.com/dms/image/.../company-logo.jpg",
"url": "https://www.linkedin.com/company/aiforenterprise/"
}
],
"page": 1,
"count": 10
}
```
---
# LinkedIn Jobs
Search LinkedIn job listings by keyword. Returns job title, company, location, posting date, job type, experience level, workplace type, industry, salary, benefits, full description, and company logo. Supports filtering by recency, job type, company, and location.
## Endpoint
```
GET /v1/linkedin/jobs
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `page` | No | Page number for pagination (default: 1) |
| `sort_by` | No | Sort order: `most_recent` or `relevance` (default: `relevance`) |
| `posted_ago` | No | Maximum job age: `1h`, `24h`, `7d`, or `30d` (default: all time) |
| `job_type` | No | Job type filter: `full_time`, `part_time`, `contract`, `temporary`, `volunteer`, `internship`, `other`. Comma-separated for multiple. |
| `company_ids` | No | Filter by company. Comma-separated LinkedIn company IDs (get IDs from the Search Companies endpoint). |
| `location_id` | No | Filter by location. A numeric LinkedIn location ID (see [Job Location IDs](/docs/linkedin-job-locations) for a full list). |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `jobs` | array | Array of matching job listings |
| `jobs[].title` | string | Job title |
| `jobs[].url` | string | Direct link to the job posting |
| `jobs[].company` | string | Company name |
| `jobs[].company_id` | string | LinkedIn company ID |
| `jobs[].company_url` | string | Link to the company's LinkedIn page |
| `jobs[].company_logo` | string | URL to the company logo |
| `jobs[].location` | string | Job location |
| `jobs[].date` | string | Date the job was posted |
| `jobs[].job_type` | string | Employment type (e.g., `full_time`, `contract`, `part_time`) |
| `jobs[].experience_level` | string | Required experience level (e.g., `entry_level`, `mid_senior`, `director`) |
| `jobs[].workplace_type` | string | Workplace arrangement: `on_site`, `remote`, or `hybrid` |
| `jobs[].industry` | string | Industry classification (when available) |
| `jobs[].job_functions` | string | Job function codes (e.g., `ENG, IT`) |
| `jobs[].description` | string | Full job description text |
| `jobs[].salary` | string | Salary information (when available) |
| `jobs[].benefits` | string | Inferred benefits (when available) |
| `jobs[].apply_url` | string | External application URL (when available) |
| `jobs[].applicants` | string | Number of applicants (when available) |
| `page` | integer | Current page number |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/jobs?query=software%20engineer&page=1&sort_by=relevance" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/jobs",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "software engineer",
"page": 1,
"sort_by": "relevance"
}
)
print(response.json())
```
## Example Response
```json
{
"jobs": [
{
"title": "Senior Software Engineer",
"url": "https://www.linkedin.com/jobs/view/4417833240/",
"company": "Stripe",
"company_id": "2135371",
"company_url": "https://www.linkedin.com/company/stripe",
"company_logo": "https://media.licdn.com/dms/image/.../company-logo.jpg",
"location": "San Francisco, CA",
"date": "2026-05-20 14:30:00",
"job_type": "full_time",
"experience_level": "mid_senior",
"workplace_type": "hybrid",
"industry": "Technology, Information and Internet",
"job_functions": "ENG, IT",
"description": "We are looking for a Senior Software Engineer to join our team...",
"salary": "$180,000 - $250,000",
"benefits": "",
"apply_url": "https://stripe.com/jobs/listing/senior-software-engineer/1234",
"applicants": "200+ applicants"
}
],
"page": 1,
"count": 25
}
```
---
# LinkedIn Job Details
Get detailed information about a specific LinkedIn job listing by URL. Returns job title, company, location, posting date, job type, experience level, workplace type, industry, salary, benefits, full description, and company logo.
## Endpoint
```
GET /v1/linkedin/job
```
**Price:** $0.002 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | LinkedIn job URL (e.g., `https://linkedin.com/jobs/view/1234567890`) or numeric job ID |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Job title |
| `url` | string | Direct link to the job posting |
| `company` | string | Company name |
| `company_id` | string | LinkedIn company ID |
| `company_url` | string | Link to the company's LinkedIn page |
| `company_logo` | string | URL to the company logo |
| `location` | string | Job location |
| `date` | string | Date the job was posted |
| `job_type` | string | Employment type (e.g., `full_time`, `contract`, `part_time`) |
| `experience_level` | string | Required experience level (e.g., `entry_level`, `mid_senior`, `director`) |
| `workplace_type` | string | Workplace arrangement: `on_site`, `remote`, or `hybrid` |
| `industry` | string | Industry classification (when available) |
| `job_functions` | string | Job function codes (e.g., `ENG, IT`) |
| `description` | string | Full job description text |
| `salary` | string | Salary information (when available) |
| `benefits` | string | Inferred benefits (when available) |
| `apply_url` | string | External application URL (when available) |
| `applicants` | string | Number of applicants (when available) |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/linkedin/job?url=https://linkedin.com/jobs/view/4417833240" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/linkedin/job",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://linkedin.com/jobs/view/4417833240"}
)
print(response.json())
```
## Example Response
```json
{
"title": "Senior Software Engineer",
"url": "https://www.linkedin.com/jobs/view/4417833240/",
"company": "Stripe",
"company_id": "2135371",
"company_url": "https://www.linkedin.com/company/stripe",
"company_logo": "https://media.licdn.com/dms/image/.../company-logo.jpg",
"location": "San Francisco, CA",
"date": "2026-05-20 14:30:00",
"job_type": "full_time",
"experience_level": "mid_senior",
"workplace_type": "hybrid",
"industry": "Technology, Information and Internet",
"job_functions": "ENG, IT",
"description": "We are looking for a Senior Software Engineer to join our team...",
"salary": "$180,000 - $250,000",
"benefits": "",
"apply_url": "https://stripe.com/jobs/listing/senior-software-engineer/1234",
"applicants": "200+ applicants"
}
```
---
# LinkedIn Job Location IDs
The [Search Jobs](/docs/linkedin-jobs) endpoint supports filtering results by location using the `location_id` parameter. This parameter accepts a LinkedIn location ID (also known as a geo URN).
## Using the location_id parameter
Pass a numeric location ID to the `location_id` parameter to filter job results to that location. Location IDs can represent countries, states/provinces, metro areas, or cities.
### Example: Jobs in the United States
```bash
curl "https://apidirect.io/v1/linkedin/jobs?query=software%20engineer&location_id=103644278" \
-H "X-API-Key: YOUR_API_KEY"
```
### Example: Jobs in London, United Kingdom
```bash
curl "https://apidirect.io/v1/linkedin/jobs?query=data%20analyst&location_id=102257491" \
-H "X-API-Key: YOUR_API_KEY"
```
### Example: Jobs in the San Francisco Bay Area
```bash
curl "https://apidirect.io/v1/linkedin/jobs?query=product%20manager&location_id=90000084" \
-H "X-API-Key: YOUR_API_KEY"
```
## Common location IDs
### Countries
| Location | ID |
|----------|----|
| United States | 103644278 |
| United Kingdom | 101165590 |
| Canada | 101174742 |
| Germany | 101282230 |
| France | 105015875 |
| India | 102713980 |
| Australia | 101452733 |
| Netherlands | 102890719 |
| Singapore | 102454443 |
| Japan | 101355337 |
| Spain | 105646813 |
| Italy | 103350119 |
| Sweden | 105117694 |
| Switzerland | 106693272 |
| Ireland | 104738515 |
| Israel | 101620260 |
| South Korea | 105149562 |
| Mexico | 103323778 |
| Poland | 105072130 |
### US States
| Location | ID |
|----------|----|
| California | 102095887 |
| New York | 105080838 |
| Texas | 102748797 |
| Florida | 101318387 |
| Illinois | 101949407 |
| Pennsylvania | 102986501 |
| Georgia | 103950076 |
| Ohio | 106981407 |
| North Carolina | 103255397 |
| Virginia | 101630962 |
| New Jersey | 101651951 |
| Massachusetts | 101098412 |
| Washington | 103977389 |
| Colorado | 105763813 |
| Arizona | 106032500 |
| Michigan | 103051080 |
| Tennessee | 104629187 |
### Major US Cities
| Location | ID |
|----------|----|
| New York City, New York | 102571732 |
| Los Angeles, California | 102448103 |
| San Francisco, California | 102277331 |
| Chicago, Illinois | 103112676 |
| Seattle, Washington | 104116203 |
| Austin, Texas | 104472865 |
| Denver, Colorado | 103736294 |
| Washington, DC | 104383890 |
| Atlanta, Georgia | 106224388 |
| Dallas, Texas | 104194190 |
| Houston, Texas | 103743442 |
| Miami, Florida | 102394087 |
| San Diego, California | 103918656 |
| Portland, Oregon | 104727230 |
| Minneapolis, Minnesota | 103039849 |
| Nashville, Tennessee | 105573479 |
| Raleigh, North Carolina | 100197101 |
| Phoenix, Arizona | 100219842 |
| Philadelphia, Pennsylvania | 104937023 |
### US Metro Areas
| Location | ID |
|----------|----|
| San Francisco Bay Area | 90000084 |
| Greater Chicago Area | 90000014 |
| Dallas-Fort Worth Metroplex | 90000031 |
| Greater Houston | 90000042 |
| Greater Los Angeles Area | 90000049 |
| Atlanta Metropolitan Area | 90000052 |
| Miami-Fort Lauderdale Area | 90000056 |
| Austin, Texas Metropolitan Area | 90000064 |
| Greater New York City Area | 90000070 |
| Greater Philadelphia | 90000077 |
| Portland, Oregon Metropolitan Area | 90000079 |
| Washington DC-Baltimore Area | 90000097 |
| Greater Minneapolis-St. Paul Area | 90000512 |
| Nashville Metropolitan Area | 90000536 |
| Greater Phoenix Area | 90000620 |
| Raleigh-Durham-Chapel Hill Area | 90000664 |
### Canadian Cities
| Location | ID |
|----------|----|
| Toronto, Ontario | 100025096 |
| Montreal, Quebec | 101728226 |
| Vancouver, British Columbia | 103366113 |
| Calgary, Alberta | 102199904 |
| Ottawa, Ontario | 106234700 |
| Edmonton, Alberta | 106535873 |
| Greater Toronto Area | 90009551 |
### European Cities
| Location | ID |
|----------|----|
| London, England, United Kingdom | 102257491 |
| Berlin, Germany | 103035651 |
| Amsterdam, Netherlands | 102011674 |
| Paris, France | 106383538 |
| Dublin, Ireland | 105178154 |
| Barcelona, Spain | 105088894 |
| Munich (District), Germany | 105264689 |
| Stockholm, Sweden | 100907646 |
| Zurich, Switzerland | 102436504 |
| Madrid, Spain | 100994331 |
| Milan, Italy | 102873640 |
| Copenhagen, Denmark | 106743989 |
| Frankfurt am Main, Germany | 106150090 |
| Düsseldorf, Germany | 104008204 |
| Cologne, Germany | 102426246 |
| Stuttgart, Germany | 102473731 |
| Lyon, France | 103815258 |
| Marseille, France | 103857854 |
| Toulouse, France | 105073465 |
| Bordeaux, France | 104787182 |
| London Area, United Kingdom | 90009496 |
| Greater Munich Metropolitan Area | 90009735 |
| Greater Paris Metropolitan Region | 90009659 |
| Greater Barcelona Metropolitan Area | 90009761 |
| Greater Madrid Metropolitan Area | 90009790 |
### Asia-Pacific Cities
| Location | ID |
|----------|----|
| Singapore | 102454443 |
| Tokyo, Japan | 103925994 |
| Sydney, Australia | 104769905 |
| Melbourne, Australia | 100992797 |
| Bengaluru (Bangalore), India | 105214831 |
| Mumbai, India | 106164952 |
| Hong Kong | 103291313 |
| Seoul, South Korea | 103588929 |
| Dubai, United Arab Emirates | 106204383 |
| Delhi, India | 106187582 |
| Hyderabad, India | 105556991 |
| Greater Tokyo Area | 90009987 |
| Greater Sydney Area | 90009524 |
| Greater Melbourne Area | 90009521 |
## Full location list
The complete list of location IDs is available as a JSON file:
**[Download linkedin-job-locations.json](/static/linkedin-job-locations.json)**
The JSON file contains thousands of locations with the following format:
```json
[
{
"id": "103644278",
"name": "United States"
},
{
"id": "102095887",
"name": "California, United States"
},
{
"id": "102277331",
"name": "San Francisco, California, United States"
}
]
```
You can search this file for the location you need and use the `id` value as the `location_id` parameter.
## Finding location IDs from LinkedIn
If the location you need is not in the list above, you can find its ID directly from LinkedIn:
1. Go to [linkedin.com/jobs](https://www.linkedin.com/jobs/) and sign in
2. Enter any search term and click the **Location** filter
3. Type the location you want and select it from the dropdown
4. Run the search
5. Look at the URL in your browser's address bar. It will contain a `geoId` parameter:
```
https://www.linkedin.com/jobs/search/?geoId=103644278&keywords=...
```
The number after `geoId=` is the location ID. In this example, `103644278` is the ID for the United States.
If the URL contains `f_PP` instead of `geoId`, the value after `f_PP=` is the same location ID:
```
https://www.linkedin.com/jobs/search/?f_PP=103644278&keywords=...
```
---
# Twitter Posts
Search Twitter/X posts by keyword. Returns tweet content, author username, URL, publication date, and engagement metrics (likes, retweets, replies, views, and more). Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/twitter/posts
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `sort_by` | No | Sort order: `most_recent` or `relevance` (default: `most_recent`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching tweets |
| `posts[].title` | string | Tweet title (format: `@username on X`) |
| `posts[].url` | string | Direct link to the tweet |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Twitter username |
| `posts[].source` | string | `"Twitter (X)"` |
| `posts[].domain` | string | `"x.com"` |
| `posts[].snippet` | string | Tweet content text |
| `posts[].likes` | integer | Number of likes |
| `posts[].retweets` | integer | Number of retweets |
| `posts[].replies` | integer | Number of replies |
| `posts[].quotes` | integer | Number of quote tweets |
| `posts[].bookmarks` | integer | Number of bookmarks |
| `posts[].views` | integer/null | Number of views (`null` when unavailable) |
| `posts[].author_followers` | integer | Author's follower count |
| `posts[].author_verified` | boolean | Whether the author is verified (blue checkmark) |
| `posts[].lang` | string | Tweet language code (e.g., `"en"`) |
| `posts[].is_reply` | boolean | Whether the tweet is a reply |
| `posts[].is_quote` | boolean | Whether the tweet is a quote tweet |
| `posts[].hashtags` | string[] | Hashtags used in the tweet |
| `posts[].user_mentions` | string[] | Usernames mentioned in the tweet |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/posts?query=AI&pages=2&sort_by=most_recent" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "AI",
"pages": 2,
"sort_by": "most_recent"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@username on X",
"url": "https://twitter.com/username/status/...",
"date": "2024-01-15 14:30:00",
"author": "username",
"source": "Twitter (X)",
"domain": "x.com",
"snippet": "Tweet content here...",
"likes": 142,
"retweets": 38,
"replies": 12,
"quotes": 5,
"bookmarks": 23,
"views": 18420,
"author_followers": 5243,
"author_verified": false,
"lang": "en",
"is_reply": false,
"is_quote": false,
"hashtags": ["AI", "MachineLearning"],
"user_mentions": ["OpenAI"],
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"pages": 2,
"count": 40
}
```
---
# Twitter Users
Search Twitter/X users by keyword. Returns profile data including username, display name, bio, follower/following counts, verification status, and profile image. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/twitter/users
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `users` | array | Array of matching user profiles |
| `users[].username` | string | Twitter username (handle) |
| `users[].name` | string | Display name |
| `users[].user_id` | string | Twitter user ID |
| `users[].description` | string | Bio / profile description |
| `users[].followers_count` | integer | Number of followers |
| `users[].following_count` | integer | Number of accounts followed |
| `users[].tweet_count` | integer | Total tweets posted |
| `users[].verified` | boolean | Whether the user is verified (blue checkmark) |
| `users[].profile_image_url` | string | URL to profile image |
| `users[].created_at` | string/null | Account creation date |
| `users[].url` | string | Link to the profile |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/users?query=AI&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/users",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "AI",
"pages": 1
}
)
print(response.json())
```
## Example Response
```json
{
"users": [
{
"username": "OpenAI",
"name": "OpenAI",
"user_id": "4398626122",
"description": "Creating safe AGI that benefits all of humanity.",
"followers_count": 3842150,
"following_count": 0,
"tweet_count": 2145,
"verified": true,
"profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
"created_at": "2015-12-09 20:42:45",
"url": "https://twitter.com/OpenAI"
}
],
"pages": 1,
"count": 20
}
```
---
# Twitter User Profile
Get detailed profile information for a Twitter/X user by username. Returns account details, follower/following counts, bio, verification status, and account metadata.
## Endpoint
```
GET /v1/twitter/user
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Twitter username (without @, max 50 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `user` | object | User profile data |
| `user.username` | string | Twitter username |
| `user.name` | string | Display name |
| `user.user_id` | string | Twitter user ID (rest_id) |
| `user.description` | string | Bio / profile description |
| `user.url` | string | Link to the profile |
| `user.followers_count` | integer | Number of followers |
| `user.following_count` | integer | Number of accounts followed |
| `user.tweet_count` | integer | Total tweets posted |
| `user.favourites_count` | integer | Total tweets liked |
| `user.listed_count` | integer | Number of lists the user is on |
| `user.media_count` | integer | Number of media posts |
| `user.verified` | boolean | Whether the user is verified (blue checkmark) |
| `user.protected` | boolean | Whether the account is private |
| `user.profile_image_url` | string | URL to profile image (400x400) |
| `user.profile_banner_url` | string | URL to profile banner |
| `user.created_at` | string | Account creation date |
| `user.pinned_tweet_ids` | string[] | IDs of pinned tweets |
| `user.account_based_in` | string | Country the account is based in |
| `user.username_changes` | integer | Number of username changes |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/user?username=elonmusk" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/user",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "elonmusk"}
)
print(response.json())
```
## Example Response
```json
{
"user": {
"username": "elonmusk",
"name": "Elon Musk",
"user_id": "44196397",
"description": "",
"url": "https://twitter.com/elonmusk",
"followers_count": 235918920,
"following_count": 1292,
"tweet_count": 98359,
"favourites_count": 214306,
"listed_count": 167743,
"media_count": 4372,
"verified": true,
"protected": false,
"profile_image_url": "https://pbs.twimg.com/profile_images/.../photo_400x400.jpg",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/...",
"created_at": "2009-06-02 20:12:29",
"pinned_tweet_ids": ["2028500984977330453"],
"account_based_in": "United States",
"username_changes": 0
}
}
```
---
# Twitter User Tweets
Get tweets posted by a specific Twitter/X user. Returns tweet content, engagement metrics, and metadata. Supports pagination to fetch multiple pages of results.
## Endpoint
```
GET /v1/twitter/user/tweets
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Twitter username (without @, max 50 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `tweets` | array | Array of tweets by the user |
| `tweets[].title` | string | Tweet title (format: `@username on X`) |
| `tweets[].url` | string | Direct link to the tweet |
| `tweets[].date` | string | Publication date and time |
| `tweets[].author` | string | Twitter username |
| `tweets[].source` | string | `"Twitter (X)"` |
| `tweets[].domain` | string | `"x.com"` |
| `tweets[].snippet` | string | Tweet content text |
| `tweets[].likes` | integer | Number of likes |
| `tweets[].retweets` | integer | Number of retweets |
| `tweets[].replies` | integer | Number of replies |
| `tweets[].quotes` | integer | Number of quote tweets |
| `tweets[].bookmarks` | integer | Number of bookmarks |
| `tweets[].views` | integer/null | Number of views |
| `tweets[].author_followers` | integer | Author's follower count |
| `tweets[].author_verified` | boolean | Whether the author is verified |
| `tweets[].lang` | string | Tweet language code |
| `tweets[].is_reply` | boolean | Whether the tweet is a reply |
| `tweets[].is_quote` | boolean | Whether the tweet is a quote tweet |
| `tweets[].hashtags` | string[] | Hashtags used in the tweet |
| `tweets[].user_mentions` | string[] | Usernames mentioned |
| `tweets[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `tweets[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `tweets[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `tweets[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `tweets[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `username` | string | Requested username |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/user/tweets?username=elonmusk&pages=2" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/user/tweets",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "elonmusk", "pages": 2}
)
print(response.json())
```
## Example Response
```json
{
"tweets": [
{
"title": "@elonmusk on X",
"url": "https://twitter.com/elonmusk/status/...",
"date": "2024-03-01 18:30:00",
"author": "elonmusk",
"source": "Twitter (X)",
"domain": "x.com",
"snippet": "Tweet content here...",
"likes": 50000,
"retweets": 8000,
"replies": 12000,
"quotes": 3000,
"bookmarks": 2000,
"views": 5000000,
"author_followers": 235918920,
"author_verified": true,
"lang": "en",
"is_reply": false,
"is_quote": false,
"hashtags": [],
"user_mentions": [],
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"username": "elonmusk",
"pages": 2,
"count": 40
}
```
---
# Twitter User Followers
Get the followers of a specific Twitter/X user. Returns profile details for each follower including username, bio, follower counts, and verification status. Supports pagination.
## Endpoint
```
GET /v1/twitter/user/followers
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Twitter username (without @, max 50 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `followers` | array | Array of follower profiles |
| `followers[].username` | string | Follower's Twitter username |
| `followers[].name` | string | Display name |
| `followers[].user_id` | string | Twitter user ID |
| `followers[].description` | string | Bio / profile description |
| `followers[].followers_count` | integer | Number of followers they have |
| `followers[].following_count` | integer | Number of accounts they follow |
| `followers[].tweet_count` | integer | Total tweets posted |
| `followers[].verified` | boolean | Whether they are verified |
| `followers[].profile_image_url` | string | URL to profile image |
| `followers[].created_at` | string | Account creation date |
| `followers[].url` | string | Link to their profile |
| `username` | string | Requested username |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/user/followers?username=elonmusk&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/user/followers",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "elonmusk", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"followers": [
{
"username": "user123",
"name": "Example User",
"user_id": "123456789",
"description": "Tech enthusiast",
"followers_count": 5000,
"following_count": 200,
"tweet_count": 1500,
"verified": false,
"profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
"created_at": "2020-01-15 10:30:00",
"url": "https://twitter.com/user123"
}
],
"username": "elonmusk",
"pages": 1,
"count": 20
}
```
---
# Twitter User Following
Get the accounts that a specific Twitter/X user is following. Returns profile details for each followed account. Supports pagination.
## Endpoint
```
GET /v1/twitter/user/following
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Twitter username (without @, max 50 characters) |
| `pages` | No | Number of pages to fetch, 1-175 (default: 1). Each page returns ~50 accounts. Billed per page requested. |
## Deep Pagination
This endpoint supports up to **175 pages** in a single call — roughly 7,500 accounts. Pagination stops early when the account has no more accounts to return, or when the response approaches the maximum size, so `count` may be lower than `pages` × 50.
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `following` | array | Array of followed user profiles |
| `following[].username` | string | Twitter username |
| `following[].name` | string | Display name |
| `following[].user_id` | string | Twitter user ID |
| `following[].description` | string | Bio / profile description |
| `following[].followers_count` | integer | Number of followers they have |
| `following[].following_count` | integer | Number of accounts they follow |
| `following[].tweet_count` | integer | Total tweets posted |
| `following[].verified` | boolean | Whether they are verified |
| `following[].profile_image_url` | string | URL to profile image |
| `following[].created_at` | string | Account creation date |
| `following[].url` | string | Link to their profile |
| `username` | string | Requested username |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/user/following?username=elonmusk&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/user/following",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "elonmusk", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"following": [
{
"username": "SpaceX",
"name": "SpaceX",
"user_id": "34743251",
"description": "SpaceX designs, manufactures and launches...",
"followers_count": 35000000,
"following_count": 50,
"tweet_count": 5000,
"verified": true,
"profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
"created_at": "2009-04-23 19:30:00",
"url": "https://twitter.com/SpaceX"
}
],
"username": "elonmusk",
"pages": 1,
"count": 56
}
```
---
# Twitter Verified Followers
Get the verified (blue checkmark) followers of a specific Twitter/X user. Only returns followers who have a verified account. Supports pagination.
## Endpoint
```
GET /v1/twitter/user/verified-followers
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Twitter username (without @, max 50 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `verified_followers` | array | Array of verified follower profiles |
| `verified_followers[].username` | string | Twitter username |
| `verified_followers[].name` | string | Display name |
| `verified_followers[].user_id` | string | Twitter user ID |
| `verified_followers[].description` | string | Bio / profile description |
| `verified_followers[].followers_count` | integer | Number of followers they have |
| `verified_followers[].following_count` | integer | Number of accounts they follow |
| `verified_followers[].tweet_count` | integer | Total tweets posted |
| `verified_followers[].verified` | boolean | Always `true` for this endpoint |
| `verified_followers[].profile_image_url` | string | URL to profile image |
| `verified_followers[].created_at` | string | Account creation date |
| `verified_followers[].url` | string | Link to their profile |
| `username` | string | Requested username |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/user/verified-followers?username=elonmusk&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/user/verified-followers",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "elonmusk", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"verified_followers": [
{
"username": "verified_user",
"name": "Verified User",
"user_id": "987654321",
"description": "Tech CEO",
"followers_count": 500000,
"following_count": 300,
"tweet_count": 10000,
"verified": true,
"profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
"created_at": "2018-06-10 14:00:00",
"url": "https://twitter.com/verified_user"
}
],
"username": "elonmusk",
"pages": 1,
"count": 20
}
```
---
# Twitter User Replies
Get replies posted by a specific Twitter/X user. Returns the content of each reply along with engagement metrics. Supports pagination.
## Endpoint
```
GET /v1/twitter/user/replies
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Twitter username (without @, max 50 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `replies` | array | Array of replies by the user |
| `replies[].title` | string | Tweet title (format: `@username on X`) |
| `replies[].url` | string | Direct link to the reply |
| `replies[].date` | string | Publication date and time |
| `replies[].author` | string | Twitter username |
| `replies[].source` | string | `"Twitter (X)"` |
| `replies[].domain` | string | `"x.com"` |
| `replies[].snippet` | string | Reply content text |
| `replies[].likes` | integer | Number of likes |
| `replies[].retweets` | integer | Number of retweets |
| `replies[].replies` | integer | Number of replies to this reply |
| `replies[].quotes` | integer | Number of quote tweets |
| `replies[].bookmarks` | integer | Number of bookmarks |
| `replies[].views` | integer/null | Number of views |
| `replies[].author_followers` | integer | Author's follower count |
| `replies[].author_verified` | boolean | Whether the author is verified |
| `replies[].lang` | string | Tweet language code |
| `replies[].is_reply` | boolean | `true` (all entries are replies) |
| `replies[].is_quote` | boolean | Whether the reply is also a quote tweet |
| `replies[].hashtags` | string[] | Hashtags used |
| `replies[].user_mentions` | string[] | Usernames mentioned |
| `replies[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `replies[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `replies[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `replies[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `replies[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `username` | string | Requested username |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/user/replies?username=elonmusk&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/user/replies",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "elonmusk", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"replies": [
{
"title": "@elonmusk on X",
"url": "https://twitter.com/elonmusk/status/...",
"date": "2024-03-01 15:20:00",
"author": "elonmusk",
"source": "Twitter (X)",
"domain": "x.com",
"snippet": "@user Indeed, that is correct",
"likes": 5000,
"retweets": 200,
"replies": 300,
"quotes": 50,
"bookmarks": 100,
"views": 500000,
"author_followers": 235918920,
"author_verified": true,
"lang": "en",
"is_reply": true,
"is_quote": false,
"hashtags": [],
"user_mentions": ["user"],
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"username": "elonmusk",
"pages": 1,
"count": 20
}
```
---
# Twitter Tweet Details
Get detailed information for a single tweet by its ID. Returns the full tweet content, engagement metrics, author info, and metadata.
## Endpoint
```
GET /v1/twitter/tweet
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `tweet_id` | Yes | Numeric tweet ID |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `tweet` | object | Tweet data |
| `tweet.title` | string | Tweet title (format: `@username on X`) |
| `tweet.url` | string | Direct link to the tweet |
| `tweet.date` | string | Publication date and time |
| `tweet.author` | string | Twitter username |
| `tweet.source` | string | `"Twitter (X)"` |
| `tweet.domain` | string | `"x.com"` |
| `tweet.snippet` | string | Tweet content text |
| `tweet.likes` | integer | Number of likes |
| `tweet.retweets` | integer | Number of retweets |
| `tweet.replies` | integer | Number of replies |
| `tweet.quotes` | integer | Number of quote tweets |
| `tweet.bookmarks` | integer | Number of bookmarks |
| `tweet.views` | integer/null | Number of views |
| `tweet.author_followers` | integer | Author's follower count |
| `tweet.author_verified` | boolean | Whether the author is verified |
| `tweet.lang` | string | Tweet language code |
| `tweet.is_reply` | boolean | Whether the tweet is a reply |
| `tweet.is_quote` | boolean | Whether the tweet is a quote tweet |
| `tweet.hashtags` | string[] | Hashtags used |
| `tweet.user_mentions` | string[] | Usernames mentioned |
| `tweet.sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `tweet.sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `tweet.sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `tweet.sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `tweet.sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/tweet?tweet_id=1631781099415257088" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/tweet",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"tweet_id": "1631781099415257088"}
)
print(response.json())
```
## Example Response
```json
{
"tweet": {
"title": "@username on X",
"url": "https://twitter.com/username/status/1631781099415257088",
"date": "2024-01-15 14:30:00",
"author": "username",
"source": "Twitter (X)",
"domain": "x.com",
"snippet": "Full tweet content here...",
"likes": 5000,
"retweets": 1200,
"replies": 300,
"quotes": 150,
"bookmarks": 800,
"views": 250000,
"author_followers": 50000,
"author_verified": true,
"lang": "en",
"is_reply": false,
"is_quote": false,
"hashtags": ["tech"],
"user_mentions": [],
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
}
```
---
# Twitter Tweet Retweets
Get the users who retweeted a specific tweet. Returns profile details for each user who retweeted. Supports pagination.
## Endpoint
```
GET /v1/twitter/tweet/retweets
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `tweet_id` | Yes | Numeric tweet ID |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `retweets` | array | Array of user profiles who retweeted |
| `retweets[].username` | string | Twitter username |
| `retweets[].name` | string | Display name |
| `retweets[].user_id` | string | Twitter user ID |
| `retweets[].description` | string | Bio / profile description |
| `retweets[].followers_count` | integer | Number of followers |
| `retweets[].following_count` | integer | Number of accounts followed |
| `retweets[].tweet_count` | integer | Total tweets posted |
| `retweets[].verified` | boolean | Whether verified |
| `retweets[].profile_image_url` | string | URL to profile image |
| `retweets[].created_at` | string | Account creation date |
| `retweets[].url` | string | Link to their profile |
| `tweet_id` | string | Requested tweet ID |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/tweet/retweets?tweet_id=1631781099415257088&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/tweet/retweets",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"tweet_id": "1631781099415257088", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"retweets": [
{
"username": "user123",
"name": "Example User",
"user_id": "123456789",
"description": "Retweeted this!",
"followers_count": 1000,
"following_count": 500,
"tweet_count": 3000,
"verified": false,
"profile_image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
"created_at": "2019-05-20 08:15:00",
"url": "https://twitter.com/user123"
}
],
"tweet_id": "1631781099415257088",
"pages": 1,
"count": 20
}
```
---
# Twitter Tweet Quotes
Get the quote tweets for a specific tweet. Returns the full content and engagement metrics for each quote tweet. Supports pagination.
## Endpoint
```
GET /v1/twitter/tweet/quotes
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `tweet_id` | Yes | Numeric tweet ID |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `quotes` | array | Array of quote tweets |
| `quotes[].title` | string | Tweet title (format: `@username on X`) |
| `quotes[].url` | string | Direct link to the quote tweet |
| `quotes[].date` | string | Publication date and time |
| `quotes[].author` | string | Twitter username of the quoter |
| `quotes[].source` | string | `"Twitter (X)"` |
| `quotes[].domain` | string | `"x.com"` |
| `quotes[].snippet` | string | Quote tweet content |
| `quotes[].likes` | integer | Number of likes |
| `quotes[].retweets` | integer | Number of retweets |
| `quotes[].replies` | integer | Number of replies |
| `quotes[].quotes` | integer | Number of quote tweets |
| `quotes[].bookmarks` | integer | Number of bookmarks |
| `quotes[].views` | integer/null | Number of views |
| `quotes[].author_followers` | integer | Quoter's follower count |
| `quotes[].author_verified` | boolean | Whether the quoter is verified |
| `quotes[].lang` | string | Tweet language code |
| `quotes[].is_reply` | boolean | Whether it is also a reply |
| `quotes[].is_quote` | boolean | Always `true` for this endpoint |
| `quotes[].hashtags` | string[] | Hashtags used |
| `quotes[].user_mentions` | string[] | Usernames mentioned |
| `quotes[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `quotes[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `quotes[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `quotes[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `quotes[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `tweet_id` | string | Requested tweet ID |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/tweet/quotes?tweet_id=1631781099415257088&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/tweet/quotes",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"tweet_id": "1631781099415257088", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"quotes": [
{
"title": "@quoter on X",
"url": "https://twitter.com/quoter/status/...",
"date": "2024-01-16 10:00:00",
"author": "quoter",
"source": "Twitter (X)",
"domain": "x.com",
"snippet": "This is so true! Great point here.",
"likes": 200,
"retweets": 50,
"replies": 10,
"quotes": 2,
"bookmarks": 30,
"views": 15000,
"author_followers": 8000,
"author_verified": false,
"lang": "en",
"is_reply": false,
"is_quote": true,
"hashtags": [],
"user_mentions": [],
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"tweet_id": "1631781099415257088",
"pages": 1,
"count": 20
}
```
---
# Twitter Tweet Comments
Get the comments (replies) on a specific tweet. Returns the full content and engagement metrics for each reply. Supports pagination.
## Endpoint
```
GET /v1/twitter/tweet/comments
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `tweet_id` | Yes | Numeric tweet ID |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `comments` | array | Array of reply tweets |
| `comments[].title` | string | Tweet title (format: `@username on X`) |
| `comments[].url` | string | Direct link to the reply |
| `comments[].date` | string | Publication date and time |
| `comments[].author` | string | Twitter username of the commenter |
| `comments[].source` | string | `"Twitter (X)"` |
| `comments[].domain` | string | `"x.com"` |
| `comments[].snippet` | string | Reply content text |
| `comments[].likes` | integer | Number of likes |
| `comments[].retweets` | integer | Number of retweets |
| `comments[].replies` | integer | Number of replies to this comment |
| `comments[].quotes` | integer | Number of quote tweets |
| `comments[].bookmarks` | integer | Number of bookmarks |
| `comments[].views` | integer/null | Number of views |
| `comments[].author_followers` | integer | Commenter's follower count |
| `comments[].author_verified` | boolean | Whether the commenter is verified |
| `comments[].lang` | string | Tweet language code |
| `comments[].is_reply` | boolean | Always `true` for this endpoint |
| `comments[].is_quote` | boolean | Whether the reply is also a quote |
| `comments[].hashtags` | string[] | Hashtags used |
| `comments[].user_mentions` | string[] | Usernames mentioned |
| `comments[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `comments[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `comments[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `comments[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `comments[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `tweet_id` | string | Requested tweet ID |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/tweet/comments?tweet_id=1631781099415257088&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/tweet/comments",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"tweet_id": "1631781099415257088", "pages": 1}
)
print(response.json())
```
## Example Response
```json
{
"comments": [
{
"title": "@commenter on X",
"url": "https://twitter.com/commenter/status/...",
"date": "2024-01-15 15:00:00",
"author": "commenter",
"source": "Twitter (X)",
"domain": "x.com",
"snippet": "@username Great post! Totally agree.",
"likes": 50,
"retweets": 5,
"replies": 2,
"quotes": 0,
"bookmarks": 3,
"views": 5000,
"author_followers": 2500,
"author_verified": false,
"lang": "en",
"is_reply": true,
"is_quote": false,
"hashtags": [],
"user_mentions": ["username"],
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"tweet_id": "1631781099415257088",
"pages": 1,
"count": 20
}
```
---
# Twitter Trends
Get the current trending topics for a specific location on Twitter/X. Returns trend names, search queries, and tweet volumes where available.
## Endpoint
```
GET /v1/twitter/trends
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `woeid` | Yes | Where On Earth ID for the location. Use `1` for Worldwide. |
## WOEID Locations
Download the full list of 467 available locations with their WOEID values:
**[Download twitter-trends-locations.json](https://apidirect.io/static/twitter-trends-locations.json)**
Common WOEIDs:
| Location | WOEID |
|----------|-------|
| Worldwide | `1` |
| United States | `23424977` |
| United Kingdom | `23424975` |
| Canada | `23424775` |
| Australia | `23424748` |
| India | `23424848` |
| Japan | `23424856` |
| Germany | `23424829` |
| France | `23424819` |
| Brazil | `23424768` |
| New York | `2459115` |
| Los Angeles | `2442047` |
| London | `44418` |
| Tokyo | `1118370` |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `trends` | array | Array of trending topics |
| `trends[].name` | string | Trend name or hashtag |
| `trends[].query` | string | URL-encoded search query |
| `trends[].tweet_volume` | integer/null | Estimated tweet volume (null when unavailable) |
| `trends[].url` | string | Twitter search URL for this trend |
| `location` | string | Name of the location |
| `woeid` | integer | WOEID used |
| `as_of` | string | Timestamp of when trends were captured |
| `count` | integer | Number of trends returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/twitter/trends?woeid=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/twitter/trends",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"woeid": 1}
)
print(response.json())
```
## Example Response
```json
{
"trends": [
{
"name": "#TrendingTopic",
"query": "%23TrendingTopic",
"tweet_volume": 125000,
"url": "http://twitter.com/search?q=%23TrendingTopic"
},
{
"name": "Breaking News",
"query": "%22Breaking+News%22",
"tweet_volume": null,
"url": "http://twitter.com/search?q=%22Breaking+News%22"
}
],
"location": "Worldwide",
"woeid": 1,
"as_of": "2026-03-05T01:23:37Z",
"count": 50
}
```
---
# Facebook Page Details
Get detailed information about a Facebook page by URL. Returns the page name, ID, follower/like counts, categories, contact info, rating, and more.
## Endpoint
```
GET /v1/facebook/page
```
**Price:** $0.008 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | Facebook page URL (e.g. https://www.facebook.com/facebook) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `page` | object | Page profile data |
| `page.name` | string | Page display name |
| `page.page_id` | string | Facebook page ID |
| `page.url` | string | URL of the page |
| `page.type` | string | Page type (e.g. "Company") |
| `page.image` | string | URL to page profile image |
| `page.cover_image` | string | URL to page cover image |
| `page.followers` | integer | Number of followers |
| `page.likes` | integer | Number of page likes |
| `page.following` | integer | Number of accounts the page follows |
| `page.categories` | string[] | List of page categories |
| `page.intro` | string | Short intro / about text |
| `page.website` | string | Website URL listed on the page |
| `page.phone` | string | Phone number listed on the page |
| `page.email` | string | Email address listed on the page |
| `page.address` | string | Physical address listed on the page |
| `page.rating` | number | Average page rating (out of 5) |
| `page.price_range` | string | Price range indicator (e.g. "$$") |
| `page.verified` | boolean | Whether the page is verified |
| `page.delegate_page_id` | string | Delegate page ID (used for videos endpoint) |
| `page.reels_page_id` | string | Reels page ID (used for reels endpoint) |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/page?url=https://www.facebook.com/facebook" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/page",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://www.facebook.com/facebook"}
)
print(response.json())
```
## Example Response
```json
{
"page": {
"name": "Facebook",
"page_id": "100064860875397",
"url": "https://www.facebook.com/facebook",
"type": "page",
"image": "https://scontent.xx.fbcdn.net/v/t39.30808-1/380700_..._n.jpg",
"cover_image": "https://scontent.xx.fbcdn.net/v/t39.30808-6/513094_..._n.jpg",
"followers": 155000000,
"likes": null,
"following": null,
"categories": ["Page", "Internet company"],
"intro": null,
"website": "fb.me/HowToContactFB",
"phone": null,
"email": null,
"address": null,
"rating": null,
"price_range": null,
"verified": true,
"delegate_page_id": "20531316728",
"reels_page_id": "YXBwX2NvbGxlY3Rpb246cGZiaWQwcTlLYm..."
}
}
```
---
# Facebook Page Posts
Get posts from a Facebook page by page ID. Returns post content, engagement metrics, reactions breakdown, and media. Supports fetching multiple pages in a single call and optional date filtering.
## Endpoint
```
GET /v1/facebook/page/posts
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `page_id` | Yes | Facebook page ID (get from page details or page ID endpoint) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `start_date` | No | Filter posts from this date (YYYY-MM-DD) |
| `end_date` | No | Filter posts up to this date (YYYY-MM-DD) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | List of post objects |
| `posts[].post_id` | string | Unique post ID |
| `posts[].url` | string | URL to the post |
| `posts[].message` | string | Post text content |
| `posts[].date` | string | Human-readable date |
| `posts[].timestamp` | integer | Unix timestamp |
| `posts[].author_name` | string | Name of the post author |
| `posts[].author_id` | string | Author's Facebook ID |
| `posts[].author_url` | string | URL to author's profile |
| `posts[].author_profile_picture` | string | URL to author's profile picture |
| `posts[].comments_count` | integer | Number of comments |
| `posts[].reactions_count` | integer | Total number of reactions |
| `posts[].reshare_count` | integer | Number of shares |
| `posts[].reactions` | object | Breakdown of reactions by type |
| `posts[].reactions.angry` | integer | Number of angry reactions |
| `posts[].reactions.care` | integer | Number of care reactions |
| `posts[].reactions.haha` | integer | Number of haha reactions |
| `posts[].reactions.like` | integer | Number of like reactions |
| `posts[].reactions.love` | integer | Number of love reactions |
| `posts[].reactions.sad` | integer | Number of sad reactions |
| `posts[].reactions.wow` | integer | Number of wow reactions |
| `posts[].image_url` | string/null | URL to attached image, if any |
| `posts[].video` | string/null | URL to attached video, if any |
| `posts[].external_url` | string/null | External link shared in the post, if any |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of posts returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/page/posts?page_id=100064860875397" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/page/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"page_id": "100064860875397"}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"post_id": "890147362481953",
"url": "https://www.facebook.com/facebook/posts/890147362481953",
"message": "Introducing new ways to connect with the people and communities you care about most.",
"date": "2025-12-14 18:30:00",
"timestamp": 1734198600,
"author_name": "Facebook",
"author_id": "100064860875397",
"author_url": "https://www.facebook.com/facebook",
"author_profile_picture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/277546_..._n.png",
"comments_count": 1243,
"reactions_count": 18742,
"reshare_count": 3021,
"reactions": {
"angry": 84,
"care": 210,
"haha": 156,
"like": 12847,
"love": 4930,
"sad": 23,
"wow": 492
},
"image_url": "https://scontent.xx.fbcdn.net/v/t39.30808-6/472918_..._n.jpg",
"video": null,
"external_url": null,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"count": 1,
"pages": 1
}
```
---
# Facebook Page Photos
Get photos from a Facebook page by page ID. Returns photo IDs and image URLs. Supports fetching multiple pages in a single call.
## Endpoint
```
GET /v1/facebook/page/photos
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `page_id` | Yes | Facebook page ID (get from page details or page ID endpoint) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `photos` | array | List of photo objects |
| `photos[].photo_id` | string | Unique photo ID |
| `photos[].image_url` | string | URL to the image |
| `count` | integer | Number of photos returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/page/photos?page_id=100064860875397" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/page/photos",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"page_id": "100064860875397"}
)
print(response.json())
```
## Example Response
```json
{
"photos": [
{
"photo_id": "1442778724560810",
"image_url": "https://scontent.xx.fbcdn.net/v/t39.30808-6/648337_..._n.jpg"
},
{
"photo_id": "1442778694560813",
"image_url": "https://scontent.xx.fbcdn.net/v/t39.30808-6/648291_..._n.jpg"
}
],
"count": 2,
"pages": 1
}
```
---
# Facebook Page Videos
Get videos from a Facebook page. Requires the delegate_page_id which can be obtained from the page details endpoint. Returns video metadata and play counts. Supports fetching multiple pages in a single call.
## Endpoint
```
GET /v1/facebook/page/videos
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `delegate_page_id` | Yes | Delegate page ID (get from the page details endpoint `delegate_page_id` field) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `videos` | array | List of video objects |
| `videos[].video_id` | string | Unique video ID |
| `videos[].url` | string | URL to the video on Facebook |
| `videos[].description` | string | Video description |
| `videos[].thumbnail` | string | URL to the video thumbnail image |
| `videos[].play_count` | integer | Number of video plays |
| `videos[].date` | string | Formatted date (YYYY-MM-DD HH:MM:SS) |
| `videos[].timestamp` | integer | Unix timestamp |
| `videos[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `videos[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `videos[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `videos[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `videos[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of videos returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/page/videos?delegate_page_id=20531316728" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/page/videos",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"delegate_page_id": "20531316728"}
)
print(response.json())
```
## Example Response
```json
{
"videos": [
{
"video_id": "1312587094016698",
"url": "https://www.facebook.com/watch/?v=1312587094016698",
"description": "Welcome to K-Ville, Duke University's legendary tent city where students camp out for weeks just to score basketball tickets.",
"thumbnail": "https://scontent.xx.fbcdn.net/v/t15.5256-10/646502_..._n.jpg",
"play_count": 1096104,
"date": "2026-03-07 17:21:49",
"timestamp": 1772904109,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
},
{
"video_id": "1610049803578776",
"url": "https://www.facebook.com/watch/?v=1610049803578776",
"description": "No mascots were harmed during the making of this prank.",
"thumbnail": "https://scontent.xx.fbcdn.net/v/t15.5256-10/644973_..._n.jpg",
"play_count": 631559,
"date": "2026-03-05 21:51:45",
"timestamp": 1772747505
}
],
"count": 2,
"pages": 1
}
```
---
# Facebook Page Reels
Get reels from a Facebook page. Requires the reels_page_id which can be obtained from the page details endpoint. Returns reel metadata and engagement metrics. Supports fetching multiple pages in a single call.
## Endpoint
```
GET /v1/facebook/page/reels
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `reels_page_id` | Yes | Reels page ID (get from the page details endpoint `reels_page_id` field) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `reels` | array | List of reel objects |
| `reels[].video_id` | string | Unique video ID |
| `reels[].post_id` | string | Associated post ID |
| `reels[].url` | string | URL to the reel on Facebook |
| `reels[].description` | string | Reel description / caption |
| `reels[].date` | string | Human-readable date |
| `reels[].timestamp` | integer | Unix timestamp |
| `reels[].length_in_seconds` | number | Duration of the reel in seconds |
| `reels[].play_count` | integer | Number of plays |
| `reels[].comments_count` | integer | Number of comments |
| `reels[].reactions_count` | integer | Total number of reactions |
| `reels[].reshare_count` | integer | Number of shares |
| `reels[].author_name` | string | Name of the reel author |
| `reels[].author_url` | string | URL to the author's profile |
| `reels[].thumbnail` | string | URL to the reel thumbnail image |
| `reels[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `reels[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `reels[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `reels[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `reels[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of reels returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/page/reels?reels_page_id=YXBwX2NvbGxlY3Rpb246cGZiaWQwcTlLYm..." \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
# First, get the reels_page_id from the page details endpoint
details = requests.get(
"https://apidirect.io/v1/facebook/page",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://www.facebook.com/facebook"}
).json()
reels_page_id = details["page"]["reels_page_id"]
response = requests.get(
"https://apidirect.io/v1/facebook/page/reels",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"reels_page_id": reels_page_id}
)
print(response.json())
```
## Example Response
```json
{
"reels": [
{
"video_id": "894523017483261",
"post_id": "894523017483261_100064860875397",
"url": "https://www.facebook.com/reel/894523017483261",
"description": "What happens when you bring people together? Amazing things.",
"date": "2025-12-08 16:45:00",
"timestamp": 1733676300,
"length_in_seconds": 28.4,
"play_count": 1842093,
"comments_count": 4312,
"reactions_count": 67481,
"reshare_count": 12094,
"author_name": "Facebook",
"author_url": "https://www.facebook.com/facebook",
"thumbnail": "https://scontent.xx.fbcdn.net/v/t15.5256-10/894523_..._n.jpg",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
},
{
"video_id": "851749203847192",
"post_id": "851749203847192_100064860875397",
"url": "https://www.facebook.com/reel/851749203847192",
"description": "3 features you probably didn't know about",
"date": "2025-11-29 12:00:00",
"timestamp": 1732881600,
"length_in_seconds": 15.7,
"play_count": 934571,
"comments_count": 1829,
"reactions_count": 42318,
"reshare_count": 7203,
"author_name": "Facebook",
"author_url": "https://www.facebook.com/facebook",
"thumbnail": "https://scontent.xx.fbcdn.net/v/t15.5256-10/851749_..._n.jpg"
}
],
"count": 2,
"pages": 1
}
```
---
# Facebook Page Reviews
Get reviews for a Facebook page by page ID. Returns review text, recommendation status, and author info. Supports fetching multiple pages in a single call.
## Endpoint
```
GET /v1/facebook/page/reviews
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `page_id` | Yes | Facebook page ID (get from page details or page ID endpoint) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `reviews` | array | List of review objects |
| `reviews[].review_text` | string | Text content of the review |
| `reviews[].recommend` | boolean | Whether the reviewer recommends the page |
| `reviews[].author_name` | string | Name of the reviewer |
| `reviews[].author_url` | string | URL to the reviewer's profile |
| `reviews[].reactions_count` | integer | Number of reactions on the review |
| `reviews[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `reviews[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `reviews[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `reviews[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `reviews[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of reviews returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/page/reviews?page_id=100063543614476" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/page/reviews",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"page_id": "100063543614476"}
)
print(response.json())
```
## Example Response
```json
{
"reviews": [
{
"review_text": "Great customer service and fast response times. Highly recommend!",
"recommend": true,
"author_name": "Sarah Johnson",
"author_url": "https://www.facebook.com/profile.php?id=100048392017456",
"reactions_count": 12,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
},
{
"review_text": "Decent product but shipping took longer than expected.",
"recommend": true,
"author_name": "Michael Chen",
"author_url": "https://www.facebook.com/profile.php?id=100039284710385",
"reactions_count": 4,
"sentiment": {
"emotions": {
"joy": 10,
"trust": 30,
"fear": 0,
"surprise": 0,
"sadness": 15,
"disgust": 10,
"anger": 20,
"anticipation": 5
},
"dominant_emotion": "trust",
"emotional_intensity": 4,
"polarity": "neutral"
}
}
],
"count": 2,
"pages": 1
}
```
---
# Facebook Group Details
Get detailed information about a Facebook group by URL. Returns the group name, ID, description, privacy setting, member count, and more.
## Endpoint
```
GET /v1/facebook/group
```
**Price:** $0.008 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | Facebook group URL (e.g. https://www.facebook.com/groups/example) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `group` | object | Group data |
| `group.id` | string | Facebook group ID |
| `group.name` | string | Group name |
| `group.url` | string | URL of the group |
| `group.description` | string | Group description / about text |
| `group.privacy` | string | Privacy setting (e.g. "Public", "Private") |
| `group.members_count` | integer | Number of group members |
| `group.location` | string | Group location (if set) |
| `group.cover_photo` | string | URL to group cover photo |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/group?url=https://www.facebook.com/groups/example" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/group",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://www.facebook.com/groups/example"}
)
print(response.json())
```
## Example Response
```json
{
"group": {
"id": "482710394817253",
"name": "Example Group",
"url": "https://www.facebook.com/groups/example",
"description": "A community for sharing tips, resources, and discussions about the latest trends. Join us to connect with like-minded people from around the world.",
"privacy": "Public group",
"members_count": 85600,
"location": "New York, NY",
"cover_photo": "https://scontent.xx.fbcdn.net/v/t39.30808-6/482710_..._n.jpg"
}
}
```
---
# Facebook Group Posts
Get posts from a public Facebook group. Returns post content, author details, engagement metrics, and media. Only public groups can be scraped.
## Endpoint
```
GET /v1/facebook/group/posts
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `group_id` | Yes | Facebook group numeric ID |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `sort_by` | No | Sort order: `most_recent` or `relevance` (default: `most_recent`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of group posts |
| `posts[].post_id` | string | Unique post identifier |
| `posts[].url` | string | Direct link to the post |
| `posts[].message` | string | Post text content |
| `posts[].date` | string | Publication date and time |
| `posts[].timestamp` | integer | Unix timestamp of publication |
| `posts[].author_name` | string | Name of the post author |
| `posts[].author_id` | string | Unique identifier of the author |
| `posts[].author_url` | string | Link to the author's profile |
| `posts[].author_profile_picture` | string | URL of the author's profile picture |
| `posts[].comments_count` | integer | Number of comments |
| `posts[].reactions_count` | integer | Total number of reactions |
| `posts[].reshare_count` | integer | Number of reshares |
| `posts[].reactions` | object | Breakdown of reaction types and counts |
| `posts[].image_url` | string/null | URL of attached image, if any |
| `posts[].video` | string/null | URL to attached video, if any |
| `posts[].external_url` | string/null | External link shared in the post, if any |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of posts returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/group/posts?group_id=1439220986320043&sort_by=most_recent" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/group/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"group_id": "1439220986320043",
"sort_by": "most_recent"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"post_id": "1439220986320043_8274610293847261",
"url": "https://www.facebook.com/groups/1439220986320043/posts/8274610293847261",
"message": "Just discovered a great new Python library for data visualization. Has anyone else tried Plotly Express? The syntax is so much cleaner than matplotlib.",
"date": "2025-03-08 16:42:00",
"timestamp": 1741452120,
"author_name": "Sarah Chen",
"author_id": "100042839174625",
"author_url": "https://www.facebook.com/profile.php?id=100042839174625",
"author_profile_picture": "https://scontent.fxxx.fbcdn.net/v/t1.6435-1/profile_pic.jpg",
"comments_count": 23,
"reactions_count": 87,
"reshare_count": 12,
"reactions": {
"like": 54,
"love": 18,
"wow": 8,
"haha": 3,
"sad": 0,
"angry": 0,
"care": 4
},
"image_url": "https://scontent.fxxx.fbcdn.net/v/t39.30808-6/post_image.jpg",
"video": null,
"external_url": "https://plotly.com/python/plotly-express/",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"count": 20,
"pages": 1
}
```
---
# Facebook Group Posts Search
> **Temporarily unavailable:** This endpoint is temporarily unavailable while we upgrade it. Every request currently returns `503` with `"code": "endpoint_suspended"`, and is not billed. See the [status page](https://apidirect.io/status) for updates. The reference below describes the endpoint as it behaves when available.
Search posts within a specific Facebook group by keyword. Returns matching posts with content, author details, and engagement metrics.
## Endpoint
```
GET /v1/facebook/group/search
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `group_id` | Yes | Facebook group numeric ID |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `start_date` | No | Filter posts from this date onward (format: `YYYY-MM-DD`) |
| `end_date` | No | Filter posts up to this date (format: `YYYY-MM-DD`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching posts |
| `posts[].post_id` | string | Unique post identifier |
| `posts[].url` | string | Direct link to the post |
| `posts[].message` | string | Post text content |
| `posts[].date` | string | Publication date and time |
| `posts[].timestamp` | integer | Unix timestamp of publication |
| `posts[].author_name` | string | Name of the post author |
| `posts[].author_id` | string | Unique identifier of the author |
| `posts[].author_url` | string | Link to the author's profile |
| `posts[].author_profile_picture` | string | URL of the author's profile picture |
| `posts[].comments_count` | integer | Number of comments |
| `posts[].reactions_count` | integer | Total number of reactions |
| `posts[].reshare_count` | integer | Number of reshares |
| `posts[].reactions` | object | Breakdown of reaction types and counts |
| `posts[].image_url` | string/null | URL of attached image, if any |
| `posts[].video` | string/null | URL to attached video, if any |
| `posts[].external_url` | string/null | External link shared in the post, if any |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of posts returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/group/search?query=help&group_id=137206643664121" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/group/search",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "help",
"group_id": "137206643664121"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"post_id": "137206643664121_5920384710283746",
"url": "https://www.facebook.com/groups/137206643664121/posts/5920384710283746",
"message": "Can anyone help me debug this React component? I keep getting a hydration mismatch error when using useEffect with server-side rendering.",
"date": "2025-03-07 09:15:00",
"timestamp": 1741338900,
"author_name": "James Rivera",
"author_id": "100058271640392",
"author_url": "https://www.facebook.com/profile.php?id=100058271640392",
"author_profile_picture": "https://scontent.fxxx.fbcdn.net/v/t1.6435-1/profile_pic.jpg",
"comments_count": 41,
"reactions_count": 15,
"reshare_count": 2,
"reactions": {
"like": 10,
"love": 1,
"wow": 0,
"haha": 0,
"sad": 2,
"angry": 0,
"care": 2
},
"image_url": null,
"video": null,
"external_url": null,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"count": 15,
"pages": 1
}
```
---
# Facebook Post Comments
Get comments on a Facebook post by post ID. Returns each comment's text, author details, reaction and reply counts, publication date, and any sticker, GIF, image, or video attachment. Supports fetching multiple pages in a single call.
## Endpoint
```
GET /v1/facebook/post/comments
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `post_id` | Yes | Facebook post ID (get from Page Posts, Group Posts, or Search Posts). Accepts both `pfbid` and numeric IDs. |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `comments` | array | List of top-level comment objects |
| `comments[].comment_id` | string | Unique comment ID |
| `comments[].legacy_comment_id` | string | Numeric comment ID |
| `comments[].message` | string/null | Comment text content (null for sticker-only comments) |
| `comments[].date` | string | Human-readable date |
| `comments[].timestamp` | integer | Unix timestamp |
| `comments[].author_name` | string | Name of the comment author |
| `comments[].author_id` | string | Author's Facebook ID |
| `comments[].author_url` | string/null | URL to author's profile |
| `comments[].author_gender` | string | Author's gender when available (`MALE`, `FEMALE`, or `NEUTER`) |
| `comments[].author_profile_picture` | string | URL to author's profile picture |
| `comments[].replies_count` | integer | Number of replies to the comment |
| `comments[].reactions_count` | integer | Number of reactions on the comment |
| `comments[].is_sticker` | boolean | Whether the comment is a sticker |
| `comments[].sticker_url` | string/null | Sticker image URL, if the comment is a sticker |
| `comments[].is_gif` | boolean | Whether the comment is a GIF |
| `comments[].gif` | object/null | GIF attachment data, if any |
| `comments[].image` | object/null | Image attachment data, if any |
| `comments[].video` | object/null | Video attachment data, if any |
| `comments[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `comments[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `comments[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `comments[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `comments[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of comments returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/post/comments?post_id=pfbid02BzYRNmoznsZjci5FuztPUb9mKd9ameNVYSBweaBEvb8oEzSMjcs8nbXnMkYA5Benl" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/post/comments",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"post_id": "pfbid02BzYRNmoznsZjci5FuztPUb9mKd9ameNVYSBweaBEvb8oEzSMjcs8nbXnMkYA5Benl"}
)
print(response.json())
```
## Example Response
```json
{
"comments": [
{
"comment_id": "Y29tbWVudDo5NDM5NDIxODExMTExMzZfMTIxNzA1OTI3NjU2OTgwNw==",
"legacy_comment_id": "1217059276569807",
"message": "Even the dog wants to dominate AI",
"date": "2025-07-03 19:25:36",
"timestamp": 1751570736,
"author_name": "Gerson Stefano",
"author_id": "100006584266587",
"author_url": "https://www.facebook.com/Gerson.Stefano.48",
"author_gender": "MALE",
"author_profile_picture": "https://scontent.xx.fbcdn.net/v/t39.30808-1/462473244_..._n.jpg",
"replies_count": 0,
"reactions_count": 0,
"is_sticker": false,
"sticker_url": null,
"is_gif": false,
"gif": null,
"image": null,
"video": null
}
],
"count": 1,
"pages": 1
}
```
## Notes
- Returns top-level comments only; each comment's `replies_count` shows how many replies it has.
- Each page returns up to ~10 comments. Billing is per page requested.
- A nonexistent or unavailable post returns an empty `comments` array, as does a post with no comments.
---
# Facebook Search Posts
Search public Facebook posts by keyword. Returns post content, author details, engagement metrics, and media attachments.
## Endpoint
```
GET /v1/facebook/posts
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `start_date` | No | Filter posts from this date onward (format: `YYYY-MM-DD`) |
| `end_date` | No | Filter posts up to this date (format: `YYYY-MM-DD`) |
| `sort_by` | No | Sort order: `most_recent` or `relevance` (default: `relevance`) |
| `location_id` | No | Facebook location ID to scope results to a place. Resolve one from a place name with the [Search Locations](/docs/facebook-search-locations) endpoint. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching posts |
| `posts[].post_id` | string | Unique post identifier |
| `posts[].url` | string | Direct link to the post |
| `posts[].message` | string | Post text content |
| `posts[].date` | string | Publication date and time |
| `posts[].timestamp` | integer | Unix timestamp of publication |
| `posts[].author_name` | string | Name of the post author |
| `posts[].author_id` | string | Unique identifier of the author |
| `posts[].author_url` | string | Link to the author's profile |
| `posts[].author_profile_picture` | string | URL of the author's profile picture |
| `posts[].comments_count` | integer | Number of comments |
| `posts[].reactions_count` | integer | Total number of reactions |
| `posts[].reshare_count` | integer | Number of reshares |
| `posts[].reactions` | object | Breakdown of reaction types and counts |
| `posts[].image_url` | string/null | URL of attached image, if any |
| `posts[].video` | string/null | URL to attached video, if any |
| `posts[].external_url` | string/null | External link shared in the post, if any |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of posts returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/posts?query=artificial%20intelligence" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "artificial intelligence"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"post_id": "pfbid02kWx7vN9mJqR4hLcT3bY",
"url": "https://www.facebook.com/permalink.php?story_fbid=pfbid02kWx7vN9mJqR4hLcT3bY&id=100064837291045",
"message": "Artificial intelligence is transforming the way we approach medical diagnostics. A new study shows AI models can now detect early-stage cancers with 94% accuracy, outperforming traditional screening methods.",
"date": "2025-03-09 11:20:00",
"timestamp": 1741519200,
"author_name": "TechNews Daily",
"author_id": "100064837291045",
"author_url": "https://www.facebook.com/TechNewsDaily",
"author_profile_picture": "https://scontent.fxxx.fbcdn.net/v/t1.6435-1/profile_pic.jpg",
"comments_count": 156,
"reactions_count": 842,
"reshare_count": 203,
"reactions": {
"like": 512,
"love": 187,
"wow": 98,
"haha": 5,
"sad": 12,
"angry": 3,
"care": 25
},
"image_url": "https://scontent.fxxx.fbcdn.net/v/t39.30808-6/ai_diagnostics.jpg",
"video": null,
"external_url": "https://technewsdaily.com/ai-cancer-detection-study",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"count": 20,
"pages": 1
}
```
---
# Facebook Search Pages
Search for Facebook pages by keyword. Returns page name, URL, profile image, and verification status.
## Endpoint
```
GET /v1/facebook/pages
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `results` | array | Array of matching Facebook pages |
| `results[].name` | string | Page display name |
| `results[].facebook_id` | string | Unique numeric page identifier |
| `results[].url` | string | Direct link to the page |
| `results[].profile_url` | string | Profile URL of the page |
| `results[].image_url` | string | URL of the page's profile image |
| `results[].is_verified` | boolean | Whether the page is verified |
| `count` | integer | Number of results returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/pages?query=nike" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/pages",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "nike"
}
)
print(response.json())
```
## Example Response
```json
{
"results": [
{
"name": "Nike",
"facebook_id": "15087023444",
"url": "https://www.facebook.com/nike",
"profile_url": "https://www.facebook.com/nike",
"image_url": "https://scontent.fxxx.fbcdn.net/v/t39.30808-1/nike_logo.jpg",
"is_verified": true
},
{
"name": "Nike Running",
"facebook_id": "116784541498",
"url": "https://www.facebook.com/nikerunning",
"profile_url": "https://www.facebook.com/nikerunning",
"image_url": "https://scontent.fxxx.fbcdn.net/v/t39.30808-1/nike_running_logo.jpg",
"is_verified": true
},
{
"name": "Nike Skateboarding",
"facebook_id": "391740174562",
"url": "https://www.facebook.com/nikeskateboarding",
"profile_url": "https://www.facebook.com/nikeskateboarding",
"image_url": "https://scontent.fxxx.fbcdn.net/v/t39.30808-1/nike_sb_logo.jpg",
"is_verified": false
}
],
"count": 3,
"pages": 1
}
```
---
# Facebook Search Videos
Search for Facebook videos by keyword. Returns video details including title, description, author information, thumbnail, and view metrics.
## Endpoint
```
GET /v1/facebook/videos
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `start_date` | No | Filter videos from this date onward (format: `YYYY-MM-DD`) |
| `end_date` | No | Filter videos up to this date (format: `YYYY-MM-DD`) |
| `sort_by` | No | Sort order: `most_recent` or `relevance` (default: `relevance`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `videos` | array | Array of matching Facebook videos |
| `videos[].video_id` | string | Unique video identifier |
| `videos[].video_url` | string | Direct link to the video |
| `videos[].title` | string/null | Video title |
| `videos[].description` | string | Video description text |
| `videos[].author_name` | string | Name of the video uploader |
| `videos[].author_url` | string | Link to the author's profile or page |
| `videos[].author_verified` | boolean | Whether the author is verified |
| `videos[].thumbnail` | string | URL of the video thumbnail image |
| `videos[].time_and_views` | string/null | Display string showing upload time and view count |
| `videos[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `videos[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `videos[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `videos[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `videos[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of videos returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/videos?query=cooking" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/videos",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "cooking"
}
)
print(response.json())
```
## Example Response
```json
{
"videos": [
{
"video_id": "1048293756182940",
"video_url": "https://www.facebook.com/watch/?v=1048293756182940",
"title": "Easy 15-Minute Pasta Recipe",
"description": "Learn how to make this delicious creamy garlic pasta in just 15 minutes! Perfect for busy weeknight dinners.",
"author_name": "Tasty",
"author_url": "https://www.facebook.com/buzzfeedtasty",
"author_verified": true,
"thumbnail": "https://scontent.fxxx.fbcdn.net/v/t15.5256-10/pasta_thumbnail.jpg",
"time_and_views": "2 days ago · 1.2M views",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
},
{
"video_id": "8374920183746251",
"video_url": "https://www.facebook.com/watch/?v=8374920183746251",
"title": "Gordon Ramsay's Top 5 Cooking Tips",
"description": "Master chef Gordon Ramsay shares his essential cooking tips that every home cook should know.",
"author_name": "Gordon Ramsay",
"author_url": "https://www.facebook.com/gordonramsay",
"author_verified": true,
"thumbnail": "https://scontent.fxxx.fbcdn.net/v/t15.5256-10/ramsay_tips_thumbnail.jpg",
"time_and_views": "1 week ago · 4.5M views"
},
{
"video_id": "5928371640192837",
"video_url": "https://www.facebook.com/watch/?v=5928371640192837",
"title": "Homemade Sourdough Bread from Scratch",
"description": "Step-by-step guide to baking the perfect sourdough loaf at home. No experience needed!",
"author_name": "Home Baking Club",
"author_url": "https://www.facebook.com/HomeBakingClub",
"author_verified": false,
"thumbnail": "https://scontent.fxxx.fbcdn.net/v/t15.5256-10/sourdough_thumbnail.jpg",
"time_and_views": "3 weeks ago · 287K views"
}
],
"count": 3,
"pages": 1
}
```
---
# Facebook Search Events
Search public Facebook events by keyword. Returns event names, event IDs, and direct event page links. Filter by date range or location.
## Endpoint
```
GET /v1/facebook/events
```
**Price:** $0.008 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch (1-10, default 1). Billed per page. |
| `start_date` | No | Filter events from this date onward (format: `YYYY-MM-DD`) |
| `end_date` | No | Filter events up to this date (format: `YYYY-MM-DD`) |
| `location_id` | No | Facebook location ID to scope results to a place. Resolve one from a place name with the [Search Locations](/docs/facebook-search-locations) endpoint. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `events` | array | Array of matching events |
| `events[].event_id` | string | Unique event identifier |
| `events[].title` | string | Event name |
| `events[].url` | string | Direct link to the event page |
| `count` | integer | Number of events returned |
| `pages` | integer | Number of pages fetched |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/events?query=music%20festival" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/events",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "music festival"
}
)
print(response.json())
```
## Example Response
```json
{
"events": [
{
"event_id": "1613570396584259",
"title": "3rd Island Music Festival",
"url": "https://www.facebook.com/events/1613570396584259/"
},
{
"event_id": "947635377782868",
"title": "Outlaw Festival: Willie Nelson, Wilco, Sheryl Crow & More!",
"url": "https://www.facebook.com/events/947635377782868/"
}
],
"count": 2,
"pages": 1
}
```
---
# Facebook Search Locations
Resolve a place name (city, region, or country) to Facebook location IDs. Use a returned `id` as the `location_id` filter on the [Search Posts](/docs/facebook-search-posts) or [Search Events](/docs/facebook-search-events) endpoint to scope a search to that place.
## Endpoint
```
GET /v1/facebook/locations
```
**Price:** $0.004 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Place name to resolve, e.g. `London` or `Paris, France` (max 500 characters) |
> **Tip:** Place names are often ambiguous — "London" matches London in the UK as well as London, Ontario and London, Texas. Use the `label` field to pick the right match, and add a country or region to your query to narrow results (e.g. `query=London, United Kingdom`).
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `results` | array | Array of matching locations |
| `results[].id` | string | Facebook location ID. Pass this to Search Posts or Search Events as `location_id`. |
| `results[].label` | string | Human-readable location name (use this to disambiguate matches) |
| `results[].timezone` | string | IANA timezone of the location (e.g. `Europe/London`) |
| `count` | integer | Number of locations returned |
## Using a location ID to filter posts
Filtering posts by location is a two-step flow. First resolve the place name to an ID:
```bash
curl "https://apidirect.io/v1/facebook/locations?query=London,%20United%20Kingdom" \
-H "X-API-Key: YOUR_API_KEY"
```
Then pass the `id` from the result you want to [Search Posts](/docs/facebook-search-posts) as `location_id`:
```bash
curl "https://apidirect.io/v1/facebook/posts?query=coffee&location_id=106078429431815" \
-H "X-API-Key: YOUR_API_KEY"
```
Location filtering biases results toward the chosen place rather than applying a strict geofence, so an occasional out-of-area post may still appear.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/facebook/locations?query=London" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/facebook/locations",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"query": "London"}
)
print(response.json())
```
## Example Response
```json
{
"results": [
{
"id": "106078429431815",
"label": "London, United Kingdom",
"timezone": "Europe/London"
},
{
"id": "107624535933778",
"label": "London, Ontario",
"timezone": "America/Toronto"
},
{
"id": "108364785855057",
"label": "London, Kentucky",
"timezone": "America/New_York"
}
],
"count": 3
}
```
---
# Reddit Posts
Search Reddit posts by keyword. Returns post title, URL, subreddit, author, and content snippet. Supports multiple sort options including hot and top posts.
## Endpoint
```
GET /v1/reddit/posts
```
**Price:** $0.003 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `page` | No | Page number, 1-5 (default: 1) |
| `sort_by` | No | Sort order: `most_recent`, `relevance`, `hot`, or `top` (default: `most_recent`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching posts |
| `posts[].title` | string | Post title |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Reddit username |
| `posts[].source` | string | `"Reddit"` |
| `posts[].domain` | string | `"reddit.com"` |
| `posts[].subreddit` | string | Subreddit name |
| `posts[].snippet` | string | Post content text |
| `posts[].upvotes` | integer | Net upvotes (upvotes minus downvotes). |
| `posts[].upvote_ratio` | number | Fraction of votes that are upvotes, between 0 and 1. |
| `posts[].comments` | integer | Number of comments on the post. |
| `posts[].crossposts` | integer | Number of times the post has been crossposted. |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `page` | integer | Current page number |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/reddit/posts?query=programming&page=1&sort_by=hot" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/reddit/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "programming",
"page": 1,
"sort_by": "hot"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "Reddit post title",
"url": "https://reddit.com/r/programming/...",
"date": "2024-01-15 14:30:00",
"author": "redditor",
"source": "Reddit",
"domain": "reddit.com",
"subreddit": "programming",
"snippet": "Post content...",
"upvotes": 1247,
"upvote_ratio": 0.96,
"comments": 312,
"crossposts": 4,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"page": 1,
"count": 20
}
```
---
# Reddit Comments
Search Reddit comments by keyword. Returns comment content, parent post URL, subreddit, author, and publication date. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/reddit/comments
```
**Price:** $0.003 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-5 (default: 1) |
| `sort_by` | No | Sort order: `most_recent`, `relevance`, or `top` (default: `most_recent`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching comments |
| `posts[].title` | string | Comment title (format: `username on subreddit`) |
| `posts[].url` | string | Link to the parent post |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Reddit username |
| `posts[].source` | string | `"Reddit (Comment)"` |
| `posts[].domain` | string | `"reddit.com"` |
| `posts[].subreddit` | string | Subreddit name |
| `posts[].snippet` | string | Comment content text |
| `posts[].type` | string | `"comment"` |
| `posts[].upvotes` | integer/null | Net upvotes on the comment. `null` if the score is hidden by the subreddit or unavailable from the fallback source. |
| `posts[].post_upvotes` | integer/null | Net upvotes on the parent post. `null` if unavailable from the fallback source. |
| `posts[].post_comments` | integer/null | Total comments on the parent post. `null` if unavailable from the fallback source. |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/reddit/comments?query=python&pages=2&sort_by=relevance" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/reddit/comments",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "python",
"pages": 2,
"sort_by": "relevance"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "commenter on python",
"url": "https://reddit.com/r/python/comments/...",
"date": "2024-01-15 14:30:00",
"author": "commenter",
"source": "Reddit (Comment)",
"domain": "reddit.com",
"subreddit": "python",
"snippet": "Comment content...",
"type": "comment",
"upvotes": 42,
"post_upvotes": 1850,
"post_comments": 274,
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"pages": 2,
"count": 50
}
```
---
# Reddit Users
Search Reddit users by keyword. Returns profile data including username, karma scores, account age, bio, and moderation status.
## Endpoint
```
GET /v1/reddit/users
```
**Price:** $0.003 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `users` | array | Array of matching user profiles |
| `users[].username` | string | Reddit username |
| `users[].user_id` | string | Reddit user ID |
| `users[].description` | string | Profile bio / description |
| `users[].link_karma` | integer | Karma from posts |
| `users[].comment_karma` | integer | Karma from comments |
| `users[].total_karma` | integer | Combined post and comment karma |
| `users[].has_verified_email` | boolean | Whether the user has a verified email |
| `users[].is_gold` | boolean | Whether the user has Reddit Premium |
| `users[].is_mod` | boolean | Whether the user is a moderator |
| `users[].icon_img` | string | URL to profile avatar |
| `users[].created_at` | string/null | Account creation date |
| `users[].url` | string | Link to the profile |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/reddit/users?query=programming" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/reddit/users",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"query": "programming"}
)
print(response.json())
```
## Example Response
```json
{
"users": [
{
"username": "spez",
"user_id": "1w72",
"description": "CEO of Reddit",
"link_karma": 148670,
"comment_karma": 650342,
"total_karma": 799012,
"has_verified_email": true,
"is_gold": true,
"is_mod": true,
"icon_img": "https://styles.redditmedia.com/...",
"created_at": "2005-06-06 04:00:00",
"url": "https://reddit.com/user/spez"
}
],
"count": 25
}
```
---
# YouTube Videos
Search YouTube videos by keyword. Returns video title, URL, channel name, publication date, description, view count, video length, thumbnail, and more. Supports filtering by upload date and fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/youtube/posts
```
**Price:** $0.005 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `upload_date` | No | Filter by upload date: `last_hour`, `today`, `this_week`, `this_month`, `this_year` |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching videos |
| `posts[].title` | string | Video title |
| `posts[].url` | string | Direct link to the video |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Channel name |
| `posts[].source` | string | `"YouTube"` or `"YouTube Shorts"` |
| `posts[].domain` | string | `"youtube.com"` |
| `posts[].snippet` | string | Video description text |
| `posts[].views` | integer/null | Number of views (`null` when unavailable) |
| `posts[].video_length` | string/null | Video duration (e.g., `"14:45"`). `null` for Shorts. |
| `posts[].video_id` | string | YouTube video ID |
| `posts[].channel_id` | string | YouTube channel ID |
| `posts[].is_live` | boolean/null | Whether the video is live content |
| `posts[].type` | string | Video type (e.g., `"NORMAL"`) |
| `posts[].keywords` | string[] | Video keywords/tags |
| `posts[].thumbnail` | string | URL to the highest resolution thumbnail |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/youtube/posts?query=tutorial&pages=2&upload_date=this_week" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/youtube/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "tutorial",
"pages": 2,
"upload_date": "this_week"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "Tutorial Video Title",
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"date": "2024-01-15 14:30:00",
"author": "Channel Name",
"source": "YouTube",
"domain": "youtube.com",
"snippet": "Video description...",
"views": 86979,
"video_length": "14:45",
"video_id": "dQw4w9WgXcQ",
"channel_id": "UCeMcDx6-rOq_RlKSPehk2tQ",
"is_live": null,
"type": "NORMAL",
"keywords": [],
"thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"pages": 2,
"count": 20
}
```
---
# YouTube Channels
Search YouTube channels by keyword. Returns channel name, description, subscriber count, and thumbnail. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/youtube/channels
```
**Price:** $0.005 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `channels` | array | Array of matching channels |
| `channels[].channel_id` | string | YouTube channel ID |
| `channels[].title` | string | Channel name |
| `channels[].description` | string | Channel description |
| `channels[].subscriber_count` | string/null | Subscriber count (e.g., `"1.14K"`, `"6.44M"`) |
| `channels[].thumbnail` | string | URL to channel avatar |
| `channels[].url` | string | Link to the channel |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/youtube/channels?query=AI&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/youtube/channels",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "AI",
"pages": 1
}
)
print(response.json())
```
## Example Response
```json
{
"channels": [
{
"channel_id": "UCLKPca3kwwd-B59HNr-_lvA",
"title": "AI Engineer",
"description": "Talks, workshops, events, and training for AI Engineers.",
"subscriber_count": "377K",
"thumbnail": "https://yt3.ggpht.com/.../photo.jpg",
"url": "https://youtube.com/channel/UCLKPca3kwwd-B59HNr-_lvA"
}
],
"pages": 1,
"count": 20
}
```
---
# YouTube Channel Details
Get detailed information about a YouTube channel by channel ID, URL, or name/handle. Returns channel name, description, subscriber count, video count, total view count, country, creation date, verification status, external links, profile picture, and banner.
## Endpoint
```
GET /v1/youtube/channel
```
**Price:** $0.005 per request
**Free tier:** 50 requests/month
## Parameters
Provide exactly one of `id`, `url`, or `name`.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `id` | One required | YouTube channel ID (24 characters, starts with `UC`) |
| `url` | One required | Channel URL: `youtube.com/channel/...`, `youtube.com/@handle`, `/c/` or `/user/` forms |
| `name` | One required | Channel name or @handle (e.g. `@mkbhd` or `Linus Tech Tips`) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `channel` | object | Channel data |
| `channel.channel_id` | string | YouTube channel ID |
| `channel.channel_name` | string | Channel name |
| `channel.description` | string | Channel description |
| `channel.subscriber_count` | string/null | Subscriber count (e.g., `"16.9M"`). `null` when hidden. |
| `channel.video_count` | string/null | Number of videos (e.g., `"7.8K"`) |
| `channel.view_count` | integer/null | Exact total channel views |
| `channel.country` | string | Channel country, or empty string when not shared |
| `channel.creation_date` | string | Channel creation date (`YYYY-MM-DD`) |
| `channel.verified` | boolean | Whether the channel is verified |
| `channel.has_business_email` | boolean | Whether the channel lists a business email |
| `channel.links` | array | External links from the channel's About page (`name`, `url`) |
| `channel.profile_pic_url` | string | URL to the highest resolution channel profile picture |
| `channel.banner` | string | URL to the highest resolution channel banner, or empty string when none |
| `channel.url` | string | Link to the channel |
If the channel does not exist, the endpoint returns a `404` with `code: "channel_not_found"`.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/youtube/channel?id=UCXuqSBlHAE6Xw-yeJA0Tunw" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/youtube/channel",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"id": "UCXuqSBlHAE6Xw-yeJA0Tunw"}
)
print(response.json())
```
You can also pass a channel URL or a name/handle instead of an ID:
```bash
curl "https://apidirect.io/v1/youtube/channel?url=https://www.youtube.com/@mkbhd" \
-H "X-API-Key: YOUR_API_KEY"
curl "https://apidirect.io/v1/youtube/channel?name=Linus%20Tech%20Tips" \
-H "X-API-Key: YOUR_API_KEY"
```
## Example Response
```json
{
"channel": {
"channel_id": "UCXuqSBlHAE6Xw-yeJA0Tunw",
"channel_name": "Linus Tech Tips",
"description": "Linus Tech Tips is a passionate team of \"professionally curious\" experts in consumer technology and video production who aim to educate and entertain.",
"subscriber_count": "16.9M",
"video_count": "7.8K",
"view_count": 9633982641,
"country": "Canada",
"creation_date": "2008-11-25",
"verified": true,
"has_business_email": true,
"links": [
{
"name": "lttstore.com",
"url": "https://lttstore.com"
},
{
"name": "Twitter",
"url": "https://twitter.com/LinusTech"
}
],
"profile_pic_url": "https://yt3.googleusercontent.com/.../photo.jpg",
"banner": "https://yt3.googleusercontent.com/.../banner.jpg",
"url": "https://youtube.com/channel/UCXuqSBlHAE6Xw-yeJA0Tunw"
}
}
```
---
# YouTube Video Details
Get detailed information about a YouTube video by URL or video ID. Returns title, full description, channel name and ID, publish date, duration, view count, category, keywords, and thumbnail.
## Endpoint
```
GET /v1/youtube/video
```
**Price:** $0.005 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | YouTube video URL (`watch?v=`, `youtu.be/`, `/shorts/`, `/embed/` or `/live/` forms) or 11-character video ID |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `video` | object | Video data |
| `video.video_id` | string | YouTube video ID |
| `video.url` | string | Link to the video |
| `video.title` | string | Video title |
| `video.description` | string | Full video description |
| `video.author` | string | Channel name |
| `video.channel_id` | string | YouTube channel ID |
| `video.date` | string | Date and time the video was published (UTC) |
| `video.duration` | integer/null | Video length in seconds |
| `video.views` | integer/null | Number of views |
| `video.category` | string | YouTube category (e.g. `Music`) |
| `video.type` | string | Video type as reported by YouTube (e.g. `NORMAL`) |
| `video.is_live` | boolean | Whether the video is a live stream |
| `video.keywords` | array | The video's tags |
| `video.thumbnail` | string | URL to the highest resolution thumbnail |
If the video does not exist, the endpoint returns a `404` with `code: "video_not_found"`.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/youtube/video?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/youtube/video",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
)
print(response.json())
```
You can also pass an 11-character video ID instead of a URL:
```bash
curl "https://apidirect.io/v1/youtube/video?url=dQw4w9WgXcQ" \
-H "X-API-Key: YOUR_API_KEY"
```
## Example Response
```json
{
"video": {
"video_id": "dQw4w9WgXcQ",
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
"description": "The official video for “Never Gonna Give You Up” by Rick Astley...",
"author": "Rick Astley",
"channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"date": "2009-10-25 06:57:33",
"duration": 213,
"views": 1788679598,
"category": "Music",
"type": "NORMAL",
"is_live": false,
"keywords": ["rick astley", "Never Gonna Give You Up", "rick roll"],
"thumbnail": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/maxresdefault.webp"
}
}
```
## Notes
- Works for regular videos, Shorts, and live streams alike.
- For live streams, `is_live` is `true` and `duration` reflects the elapsed stream time so far.
---
# YouTube Video Comments
Get comments from any YouTube video by URL. Returns each comment's text, author, like count, reply count, publication date, a direct link, and up to 5 preview replies. Supports sorting by most recent or relevance, and fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/youtube/comments
```
**Price:** $0.005 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | YouTube video URL or 11-character video ID. Accepts `watch`, `youtu.be`, `shorts`, `embed`, and `live` URL forms. |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1). Each page returns up to ~100 comments. |
| `sort_by` | No | Sort order: `most_recent` (newest first) or `relevance` (default: `relevance`). |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `comments` | array | Array of comment threads (top-level comments) |
| `comments[].comment_id` | string | Unique comment ID |
| `comments[].text` | string | Comment text |
| `comments[].author` | string | Comment author's display name (handle) |
| `comments[].author_channel_id` | string | Comment author's channel ID |
| `comments[].author_channel_url` | string | Comment author's channel URL |
| `comments[].author_thumbnail` | string | Comment author's profile image URL |
| `comments[].likes` | integer | Number of likes on the comment |
| `comments[].reply_count` | integer | Total number of replies to the comment |
| `comments[].date` | string | Publication date and time |
| `comments[].updated_date` | string | Last edited date and time |
| `comments[].url` | string | Direct link to the comment |
| `comments[].video_id` | string | YouTube video ID |
| `comments[].channel_id` | string | Channel ID of the video |
| `comments[].source` | string | `"YouTube"` |
| `comments[].domain` | string | `"youtube.com"` |
| `comments[].replies` | array | Up to 5 preview replies. Each reply has `comment_id`, `text`, `author`, `author_channel_id`, `author_channel_url`, `author_thumbnail`, `likes`, `date`, `url`, `video_id`. |
| `pages` | integer | Number of pages requested (each page is billed) |
| `count` | integer | Total comments returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/youtube/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ&pages=1&sort_by=relevance" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/youtube/comments",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"pages": 1,
"sort_by": "relevance"
}
)
print(response.json())
```
## Example Response
```json
{
"comments": [
{
"comment_id": "Ugzge340dBgB75hWBm54AaABAg",
"text": "can confirm: he never gave us up",
"author": "@YouTube",
"author_channel_id": "UCBR8-60-B28hp2BmDPdntcQ",
"author_channel_url": "http://www.youtube.com/@YouTube",
"author_thumbnail": "https://yt3.ggpht.com/.../photo.jpg",
"likes": 261929,
"reply_count": 1000,
"date": "2025-04-22 19:05:08",
"updated_date": "2025-04-22 19:05:08",
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ&lc=Ugzge340dBgB75hWBm54AaABAg",
"video_id": "dQw4w9WgXcQ",
"channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
"source": "YouTube",
"domain": "youtube.com",
"replies": [
{
"comment_id": "Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR",
"text": "YOUTUBE AND ONE LIKE WOOHAAAAH",
"author": "@linganguliguliwatcha",
"author_channel_id": "UCjFRISlX-LPxiqViJAE3h6Q",
"author_channel_url": "http://www.youtube.com/@linganguliguliwatcha",
"author_thumbnail": "https://yt3.ggpht.com/.../photo.jpg",
"likes": 7026,
"date": "2025-04-22 19:14:32",
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ&lc=Ugzge340dBgB75hWBm54AaABAg.AHE8_QAWJx9AHE9eIiztxR",
"video_id": "dQw4w9WgXcQ"
}
]
}
],
"pages": 1,
"count": 100
}
```
## Notes
- A video's pinned comment may appear first regardless of `sort_by`.
- Each page returns up to ~100 comments. Billing is per page requested.
- `replies` contains up to 5 preview replies per comment; a comment's full reply count is in `reply_count`.
- Videos with comments disabled (or otherwise unavailable) return an empty `comments` array.
- A nonexistent, private, or removed video returns `404` with code `video_not_found`.
---
# Instagram Posts
Search Instagram posts by keyword. Returns post content, engagement metrics (likes, comments, shares, views), author metadata, and publication date. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/instagram/posts
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching posts |
| `posts[].title` | string | Post title (format: `@username on Instagram`) |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Instagram username |
| `posts[].source` | string | `"Instagram"` |
| `posts[].domain` | string | `"instagram.com"` |
| `posts[].snippet` | string | Post caption text |
| `posts[].likes` | integer | Number of likes |
| `posts[].comments` | integer | Number of comments |
| `posts[].shares` | integer | Number of shares |
| `posts[].reposts` | integer | Number of reposts |
| `posts[].views` | integer/null | Number of views/plays (`null` for image posts) |
| `posts[].is_video` | boolean | Whether the post is a video |
| `posts[].media_type` | string | Post type (e.g., `"feed"`, `"clips"`) |
| `posts[].author_verified` | boolean | Whether the author is verified |
| `posts[].author_name` | string | Author's display name |
| `posts[].hashtags` | string[] | Hashtags used in the caption |
| `posts[].mentions` | string[] | Usernames mentioned in the caption |
| `posts[].media_id` | string | Instagram media ID |
| `posts[].thumbnail_url` | string | URL of the post's cover image (temporary; valid ~6–24 hours) |
| `posts[].video_url` | string | Direct video URL for video posts/reels; empty for images (temporary; valid ~6–24 hours) |
| `posts[].video_duration` | number/null | Video length in seconds (`null` for images) |
| `posts[].width` | integer | Media width in pixels |
| `posts[].height` | integer | Media height in pixels |
| `posts[].carousel_media_count` | integer | Number of items in a carousel post (`0` for single-media posts) |
| `posts[].is_paid_partnership` | boolean | Whether the post is a paid partnership / branded content |
| `posts[].location` | object/null | Geotag: `name`, `city`, `lat`, `lng` (or `null`) |
| `posts[].tagged_users` | array | Users tagged in the post (`username`, `full_name`, `user_id`) |
| `posts[].coauthors` | array | Collaborators on the post (`username`, `full_name`, `user_id`, `is_verified`) |
| `posts[].carousel_media` | array | For carousel/album posts: each slide as `media_id`, `is_video`, `image_url`, `video_url`, `width`, `height` (empty for single-media posts) |
| `posts[].audio` | object/null | Audio track for reels/videos: `type` (`music` or `original`), `title`, `artist`, `audio_id`, `duration_ms` (`null` when no audio) |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/instagram/posts?query=technology&pages=2" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/instagram/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "technology",
"pages": 2
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@mrbeast on Instagram",
"url": "https://instagram.com/p/DSDh2qaEVmQ",
"date": "2025-12-09 20:16:58",
"author": "mrbeast",
"source": "Instagram",
"domain": "instagram.com",
"snippet": "How Many People Does it Take to Pull a Plane w/ @saudi_airlines",
"likes": 530176,
"comments": 5608,
"shares": 9536,
"reposts": 4353,
"views": 29667777,
"is_video": true,
"media_type": "clips",
"author_verified": true,
"author_name": "MrBeast",
"hashtags": [],
"mentions": ["saudi_airlines"],
"media_id": "3512345678901234567",
"thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/cover.jpg",
"video_url": "https://scontent.cdninstagram.com/o1/v/t2/clip.mp4",
"video_duration": 41.2,
"width": 1080,
"height": 1920,
"carousel_media_count": 0,
"is_paid_partnership": false,
"location": null,
"tagged_users": [
{"username": "saudi_airlines", "full_name": "Saudia", "user_id": "12345678"}
],
"coauthors": [],
"carousel_media": [],
"audio": {
"type": "original",
"title": "Original audio",
"artist": "mrbeast",
"audio_id": "1234567890123456",
"duration_ms": 41200
},
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"pages": 2,
"count": 20
}
```
---
# Instagram Users
Search Instagram users by keyword. Returns username, full name, user ID, verification status, privacy status, and profile picture URL.
## Endpoint
```
GET /v1/instagram/users
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `users` | array | Array of matching user profiles |
| `users[].username` | string | Instagram username |
| `users[].full_name` | string | Display name |
| `users[].user_id` | string | Instagram user ID |
| `users[].is_verified` | boolean | Whether the user is verified (blue checkmark) |
| `users[].is_private` | boolean | Whether the account is private |
| `users[].profile_pic_url` | string | URL to profile picture |
| `users[].url` | string | Link to the profile |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/instagram/users?query=photography" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/instagram/users",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"query": "photography"}
)
print(response.json())
```
## Example Response
```json
{
"users": [
{
"username": "natgeo",
"full_name": "National Geographic",
"user_id": "787132",
"is_verified": true,
"is_private": false,
"profile_pic_url": "https://scontent.cdninstagram.com/.../photo.jpg",
"url": "https://instagram.com/natgeo"
}
],
"count": 50
}
```
---
# Instagram User Profile
Get the full profile for a single Instagram user by username or profile URL. Returns biography, follower / following counts, media count, category, external link, contact info, verification status, and "About this account" info (country the account is based in, join date, verification date, former usernames).
## Endpoint
```
GET /v1/instagram/user
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
Provide exactly one of `username` or `url`.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | One required | Instagram username, with or without leading `@` (max 100 characters) |
| `url` | One required | Instagram profile URL, e.g. `https://instagram.com/natgeo` (max 500 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `user` | object | Profile data |
| `user.username` | string | Instagram username |
| `user.full_name` | string | Display name |
| `user.user_id` | string | Instagram user ID |
| `user.biography` | string | Profile biography text |
| `user.follower_count` | integer | Number of followers |
| `user.following_count` | integer | Number of accounts followed |
| `user.media_count` | integer | Total number of posts |
| `user.is_verified` | boolean | Whether the user is verified (blue checkmark) |
| `user.is_private` | boolean | Whether the account is private |
| `user.is_business` | boolean | Whether the account is a business profile |
| `user.category` | string | Business / creator category, or empty string |
| `user.external_url` | string | External link displayed on the profile |
| `user.bio_links` | array | Additional bio link objects with `url` and `title` |
| `user.profile_pic_url` | string | URL to standard-resolution profile picture |
| `user.profile_pic_url_hd` | string | URL to high-resolution profile picture |
| `user.public_email` | string | Public contact email, or empty string |
| `user.public_phone_number` | string | Public contact phone number, or empty string |
| `user.account_based_in` | string | Country the account is based in, or empty string |
| `user.date_joined` | string | Month and year the account joined Instagram (e.g. `November 2010`), or empty string |
| `user.date_joined_timestamp` | integer/null | Unix timestamp of the join date |
| `user.date_verified` | string | Month and year the account was verified, or empty string |
| `user.date_verified_timestamp` | integer/null | Unix timestamp of the verification date |
| `user.former_usernames` | integer/null | Number of former usernames the account has used |
| `user.url` | string | Link to the profile |
The "About this account" fields come from Instagram's public transparency info. Instagram does not expose it for every account, so the string fields can be empty and the `integer/null` fields `null`.
If the username does not exist, the endpoint returns a `404` with `code: "not_found"`.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/instagram/user?username=natgeo" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/instagram/user",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "natgeo"}
)
print(response.json())
```
You can also pass a profile URL instead of a username:
```bash
curl "https://apidirect.io/v1/instagram/user?url=https://www.instagram.com/natgeo/" \
-H "X-API-Key: YOUR_API_KEY"
```
## Example Response
```json
{
"user": {
"username": "natgeo",
"full_name": "National Geographic",
"user_id": "787132",
"biography": "Step into wonder and find your inner explorer with National Geographic 🌎",
"follower_count": 274777448,
"following_count": 194,
"media_count": 31593,
"is_verified": true,
"is_private": false,
"is_business": true,
"category": "",
"external_url": "http://visitstore.bio/natgeo",
"bio_links": [
{
"url": "http://visitstore.bio/natgeo",
"title": ""
}
],
"profile_pic_url": "https://scontent.cdninstagram.com/.../photo.jpg",
"profile_pic_url_hd": "https://scontent.cdninstagram.com/.../photo_hd.jpg",
"public_email": "",
"public_phone_number": "",
"account_based_in": "United States",
"date_joined": "November 2010",
"date_joined_timestamp": 1288569600,
"date_verified": "",
"date_verified_timestamp": null,
"former_usernames": 0,
"url": "https://instagram.com/natgeo"
}
}
```
---
# Instagram User Posts
Get a user's recent posts and reels (their feed) by profile URL or username. Returns post captions, engagement metrics (likes, comments, shares, views), author metadata, hashtags, and mentions. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/instagram/user/posts
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | No | Instagram profile URL, e.g. `https://instagram.com/natgeo` (max 500 characters). Provide either `url` or `username`. |
| `username` | No | Instagram username, with or without leading `@` (max 100 characters). Provide either `url` or `username`. |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1). Each page returns up to 12 posts. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
Provide exactly one of `url` or `username`.
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of the user's recent posts and reels |
| `posts[].title` | string | Post title (format: `@username on Instagram`) |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Instagram username |
| `posts[].source` | string | `"Instagram"` |
| `posts[].domain` | string | `"instagram.com"` |
| `posts[].snippet` | string | Post caption text |
| `posts[].likes` | integer | Number of likes |
| `posts[].comments` | integer | Number of comments |
| `posts[].shares` | integer | Number of shares |
| `posts[].reposts` | integer | Number of reposts |
| `posts[].views` | integer/null | Number of views/plays (`null` for image posts) |
| `posts[].is_video` | boolean | Whether the post is a video |
| `posts[].media_type` | string | Post type (e.g., `"feed"`, `"clips"`, `"carousel_container"`) |
| `posts[].author_verified` | boolean | Whether the author is verified |
| `posts[].author_name` | string | Author's display name |
| `posts[].hashtags` | string[] | Hashtags used in the caption |
| `posts[].mentions` | string[] | Usernames mentioned in the caption |
| `posts[].media_id` | string | Instagram media ID |
| `posts[].thumbnail_url` | string | URL of the post's cover image (temporary; valid ~6–24 hours) |
| `posts[].video_url` | string | Direct video URL for video posts/reels; empty for images (temporary; valid ~6–24 hours) |
| `posts[].video_duration` | number/null | Video length in seconds (`null` for images) |
| `posts[].width` | integer | Media width in pixels |
| `posts[].height` | integer | Media height in pixels |
| `posts[].carousel_media_count` | integer | Number of items in a carousel post (`0` for single-media posts) |
| `posts[].is_paid_partnership` | boolean | Whether the post is a paid partnership / branded content |
| `posts[].location` | object/null | Geotag: `name`, `city`, `lat`, `lng` (or `null`) |
| `posts[].tagged_users` | array | Users tagged in the post (`username`, `full_name`, `user_id`) |
| `posts[].coauthors` | array | Collaborators on the post (`username`, `full_name`, `user_id`, `is_verified`) |
| `posts[].carousel_media` | array | For carousel/album posts: each slide as `media_id`, `is_video`, `image_url`, `video_url`, `width`, `height` (empty for single-media posts) |
| `posts[].audio` | object/null | Audio track for reels/videos: `type` (`music` or `original`), `title`, `artist`, `audio_id`, `duration_ms` (`null` when no audio) |
| `posts[].is_pinned` | boolean | Whether the post is pinned to the top of the user's profile |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/instagram/user/posts?url=https://instagram.com/natgeo&pages=2" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/instagram/user/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"url": "https://instagram.com/natgeo",
"pages": 2
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@natgeo on Instagram",
"url": "https://instagram.com/p/DZkn1f0Flsc",
"date": "2026-06-14 16:00:06",
"author": "natgeo",
"source": "Instagram",
"domain": "instagram.com",
"snippet": "Photograph by @petelas | A curious fox in the snow...",
"likes": 530176,
"comments": 5608,
"shares": 9536,
"reposts": 4353,
"views": null,
"is_video": false,
"media_type": "carousel_container",
"author_verified": true,
"author_name": "National Geographic",
"hashtags": [],
"mentions": ["petelas"],
"media_id": "3520497851234567890",
"thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/cover.jpg",
"video_url": "",
"video_duration": null,
"width": 1080,
"height": 1350,
"carousel_media_count": 3,
"is_paid_partnership": false,
"location": {
"name": "Serengeti National Park",
"city": "Arusha",
"lat": -2.3333,
"lng": 34.8333
},
"tagged_users": [
{"username": "natgeotv", "full_name": "National Geographic TV", "user_id": "18091046"}
],
"coauthors": [],
"carousel_media": [
{"media_id": "3520497851234567891", "is_video": false, "image_url": "https://scontent.cdninstagram.com/v/t51.82787-15/slide1.jpg", "video_url": "", "width": 1080, "height": 1350},
{"media_id": "3520497851234567892", "is_video": false, "image_url": "https://scontent.cdninstagram.com/v/t51.82787-15/slide2.jpg", "video_url": "", "width": 1080, "height": 1350},
{"media_id": "3520497851234567893", "is_video": true, "image_url": "https://scontent.cdninstagram.com/v/t51.82787-15/slide3.jpg", "video_url": "https://scontent.cdninstagram.com/o1/v/t2/slide3.mp4", "width": 1080, "height": 1920}
],
"audio": null,
"is_pinned": false
}
],
"pages": 2,
"count": 24
}
```
## Notes
- Posts are returned newest first, up to 12 per page. Use `pages` (1-10) to fetch more in a single call; you are billed per page requested.
- Both regular posts and Reels are returned. Use `media_type` to distinguish them (`clips` for Reels).
- If the account does not exist, the endpoint returns `404` with code `not_found`. You are not charged for `not_found` responses.
- Private accounts return no posts.
---
# Instagram Post Details
Get full details for a single Instagram post, reel, or IGTV video by URL or shortcode. Returns the caption, like / comment / share / view counts, media URLs, carousel slides, audio track info, tagged users, location, and author details.
## Endpoint
```
GET /v1/instagram/post
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
Provide exactly one of `url` or `code`.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | One required | Instagram post, reel, or story URL, e.g. `https://www.instagram.com/p/CxYQJO8xuC6/` (max 500 characters). `/p/`, `/reel/`, `/tv/`, and `/stories/` URLs are accepted. |
| `code` | One required | The post's shortcode from the URL, e.g. `CxYQJO8xuC6`, or its numeric media ID (max 50 characters) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to the post. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `post` | object | Post data |
| `post.title` | string | Post title (format: `@username on Instagram`) |
| `post.url` | string | Direct link to the post |
| `post.date` | string | Publication date and time |
| `post.date_timestamp` | integer/null | Unix timestamp of the publication date |
| `post.author` | string | Instagram username |
| `post.author_id` | string | Author's Instagram user ID |
| `post.source` | string | Platform name (Instagram) |
| `post.domain` | string | instagram.com |
| `post.snippet` | string | Post caption text |
| `post.likes` | integer | Number of likes |
| `post.comments` | integer | Number of comments |
| `post.shares` | integer | Number of shares |
| `post.reposts` | integer | Number of reposts |
| `post.views` | integer/null | Number of views/plays (null for image posts) |
| `post.is_video` | boolean | Whether the post is a video |
| `post.media_type` | string | Post type: `feed`, `clips` (reel), or `carousel_container` |
| `post.author_verified` | boolean | Whether the author is verified |
| `post.author_name` | string | Author's display name |
| `post.hashtags` | array | Hashtags used in the caption |
| `post.mentions` | array | Usernames mentioned in the caption |
| `post.media_id` | string | Instagram media ID |
| `post.thumbnail_url` | string | URL of the post's cover image (temporary; valid ~6-24 hours) |
| `post.video_url` | string | Direct video URL for video posts/reels, empty for images (temporary; valid ~6-24 hours) |
| `post.video_duration` | number/null | Video length in seconds (null for images) |
| `post.width` | integer | Media width in pixels |
| `post.height` | integer | Media height in pixels |
| `post.carousel_media_count` | integer | Number of items in a carousel post (0 for single-media posts) |
| `post.is_paid_partnership` | boolean | Whether the post is a paid partnership / branded content |
| `post.location` | object/null | Geotag with `name`, `city`, `lat`, `lng` (null when the post has no location) |
| `post.tagged_users` | array | Users tagged in the post (`username`, `full_name`, `user_id`) |
| `post.coauthors` | array | Collaborators on the post (`username`, `full_name`, `user_id`, `is_verified`) |
| `post.carousel_media` | array | For carousel/album posts: one entry per slide with `media_id`, `is_video`, `image_url`, `video_url`, `width`, `height` (empty for single-media posts) |
| `post.audio` | object/null | Audio track for reels/videos: `type` (`music` or `original`), `title`, `artist`, `audio_id`, `duration_ms` (null when the post has no audio) |
| `post.is_pinned` | boolean | Whether the post is pinned to the top of the author's profile |
| `post.accessibility_caption` | string | Auto-generated alt text describing the image (empty when unavailable) |
| `post.sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `post.sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `post.sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `post.sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `post.sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
If the post does not exist, the endpoint returns a `404` with `code: "not_found"`.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/instagram/post?url=https://www.instagram.com/reel/DaTSSukB-Lb/" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/instagram/post",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://www.instagram.com/reel/DaTSSukB-Lb/"}
)
print(response.json())
```
You can also pass the post's shortcode instead of a URL:
```bash
curl "https://apidirect.io/v1/instagram/post?code=DaTSSukB-Lb" \
-H "X-API-Key: YOUR_API_KEY"
```
## Example Response
```json
{
"post": {
"title": "@instagram on Instagram",
"url": "https://instagram.com/p/DaTSSukB-Lb",
"date": "2026-07-02 18:58:11",
"date_timestamp": 1783018691,
"author": "instagram",
"author_id": "25025320",
"source": "Instagram",
"domain": "instagram.com",
"snippet": "this glow >>> #InTheMoment Video by @chriswoodlight Music by Amory Reel",
"likes": 167541,
"comments": 2493,
"shares": 13063,
"reposts": 0,
"views": 21786137,
"is_video": true,
"media_type": "clips",
"author_verified": true,
"author_name": "Instagram",
"hashtags": ["#InTheMoment"],
"mentions": ["chriswoodlight"],
"media_id": "3932567351408976603",
"thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/cover.jpg",
"video_url": "https://scontent.cdninstagram.com/o1/v/t2/video.mp4",
"video_duration": 22.03,
"width": 720,
"height": 1280,
"carousel_media_count": 0,
"is_paid_partnership": false,
"location": null,
"tagged_users": [
{"username": "chriswoodlight", "full_name": "Chris Wood Light Studio", "user_id": "2107151539"}
],
"coauthors": [],
"carousel_media": [],
"audio": {
"type": "music",
"title": "her garden",
"artist": "Amory Reel",
"audio_id": "7115801341882925",
"duration_ms": 89205
},
"is_pinned": false,
"accessibility_caption": ""
}
}
```
## Notes
- `thumbnail_url`, `video_url`, and carousel media URLs are temporary CDN links that expire after roughly 6-24 hours. Request the post again whenever you need fresh links.
- Reels return `media_type` `clips` plus `views`, `video_url`, `video_duration`, and the `audio` track. Carousel posts return `media_type` `carousel_container` and one `carousel_media` entry per slide.
---
# Threads Posts
Search Threads posts by keyword. Returns post text, engagement metrics (likes, replies, reposts, quotes, reshares), author metadata, attached media, and link previews.
## Endpoint
```
GET /v1/threads/posts
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching posts |
| `posts[].title` | string | Post title (format: @username on Threads) |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time (UTC, YYYY-MM-DD HH:MM:SS) |
| `posts[].author` | string | Author's Threads username |
| `posts[].source` | string | `"Threads"` |
| `posts[].domain` | string | `"threads.com"` |
| `posts[].snippet` | string | Post text content |
| `posts[].likes` | integer | Number of likes |
| `posts[].replies` | integer | Number of replies |
| `posts[].reposts` | integer | Number of reposts |
| `posts[].quotes` | integer | Number of quote posts |
| `posts[].reshares` | integer | Number of times reshared to other surfaces |
| `posts[].author_name` | string | Author's display name (empty on some search results) |
| `posts[].author_verified` | boolean | Whether the author is verified |
| `posts[].is_reply` | boolean | Whether the post is a reply |
| `posts[].media_type` | string | Post type: `text`, `image`, `video`, or `carousel` |
| `posts[].image_url` | string | Cover image URL for image/video/carousel posts, empty for text-only (temporary; valid ~6-24 hours) |
| `posts[].video_url` | string | Direct video URL for video posts, empty otherwise (temporary; valid ~6-24 hours) |
| `posts[].width` | integer | Media width in pixels (0 when not applicable) |
| `posts[].height` | integer | Media height in pixels (0 when not applicable) |
| `posts[].has_audio` | boolean | Whether the post's video has audio |
| `posts[].reply_control` | string | Who can reply (e.g. `everyone`) |
| `posts[].hashtags` | array | Hashtags used in the post |
| `posts[].mentions` | array | Usernames mentioned in the post |
| `posts[].carousel_media` | array | Slides for carousel posts (`media_id`, `is_video`, `image_url`, `video_url`, `width`, `height`); empty otherwise |
| `posts[].link_preview` | object \| null | Link preview for posts sharing a URL (`url`, `display_url`, `title`, `description`, `image_url`, `favicon_url`), or null |
| `posts[].quoted_post` | object \| null | The embedded quoted/reposted post (same post shape), or null |
| `posts[].post_id` | string | Threads post ID |
| `posts[].code` | string | Post shortcode (used in the post URL) |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/threads/posts?query=technology" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/threads/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"query": "technology"}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@technologybrief on Threads",
"url": "https://www.threads.com/@technologybrief/post/DaqCqtWHdiU",
"date": "2026-07-08 14:22:31",
"author": "technologybrief",
"source": "Threads",
"domain": "threads.com",
"snippet": "Most people don't realize how many tech giants are already deep in bear-market territory.",
"likes": 1284,
"replies": 96,
"reposts": 41,
"quotes": 12,
"reshares": 23,
"author_name": "Technology Brief",
"author_verified": true,
"is_reply": false,
"media_type": "image",
"image_url": "https://scontent.cdninstagram.com/v/t51.82787-15/photo.jpg",
"video_url": "",
"width": 1080,
"height": 1350,
"has_audio": false,
"reply_control": "everyone",
"hashtags": [],
"mentions": [],
"carousel_media": [],
"link_preview": null,
"quoted_post": null,
"post_id": "3938972555089402004",
"code": "DaqCqtWHdiU"
}
],
"count": 25
}
```
---
# Threads Search Users
Search Threads users by keyword. Returns username, display name, user ID, verification status, privacy status, and profile picture URL.
## Endpoint
```
GET /v1/threads/users
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `users` | array | Array of matching user profiles |
| `users[].username` | string | Threads username |
| `users[].full_name` | string | Display name |
| `users[].user_id` | string | Threads user ID |
| `users[].is_verified` | boolean | Whether the user is verified |
| `users[].is_private` | boolean | Whether the account is private |
| `users[].profile_pic_url` | string | URL to profile picture |
| `users[].url` | string | Link to the profile |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/threads/users?query=technology" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/threads/users",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"query": "technology"}
)
print(response.json())
```
## Example Response
```json
{
"users": [
{
"username": "technologyreview",
"full_name": "MIT Technology Review",
"user_id": "63213270539",
"is_verified": true,
"is_private": false,
"profile_pic_url": "https://scontent.cdninstagram.com/.../photo.jpg",
"url": "https://www.threads.com/@technologyreview"
}
],
"count": 9
}
```
## Notes
- Search Users returns basic discovery data only. For a full profile — biography, follower count, and bio links — use the [User Profile](/docs/threads-user) endpoint.
- Each request returns a single page of matching users (typically up to 15).
---
# Threads User Profile
Get the full profile for a single Threads user by username. Returns biography, follower count, verification status, profile picture (standard and high resolution), the external bio links displayed on the profile, and the topic tags shown on the profile.
## Endpoint
```
GET /v1/threads/user
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Threads username, with or without leading @ (max 100 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `user` | object | Profile data object |
| `user.username` | string | Threads username |
| `user.full_name` | string | Display name |
| `user.user_id` | string | Threads user ID |
| `user.biography` | string | Profile biography text |
| `user.follower_count` | integer | Number of followers |
| `user.is_verified` | boolean | Whether the user is verified |
| `user.is_private` | boolean | Whether the account is private |
| `user.profile_pic_url` | string | URL to standard-resolution profile picture |
| `user.profile_pic_url_hd` | string | URL to high-resolution profile picture |
| `user.bio_links` | array | External bio link objects shown on the profile (`url`, `title`); empty array when the profile has no links |
| `user.profile_tags` | array | Topic tags shown on the profile (`name`, `display_name`); empty array when none |
| `user.url` | string | Link to the profile |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/threads/user?username=zuck" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/threads/user",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "zuck"}
)
print(response.json())
```
## Example Response
```json
{
"user": {
"username": "zuck",
"full_name": "Mark Zuckerberg",
"user_id": "63055343223",
"biography": "Mostly superintelligence and MMA takes",
"follower_count": 5673124,
"is_verified": true,
"is_private": false,
"profile_pic_url": "https://scontent.cdninstagram.com/.../photo.jpg",
"profile_pic_url_hd": "https://scontent.cdninstagram.com/.../photo_640x640.jpg",
"bio_links": [
{"url": "https://www.meta.com", "title": "meta.com"}
],
"profile_tags": [
{"name": "aithreads", "display_name": "AI Threads"}
],
"url": "https://www.threads.com/@zuck"
}
}
```
---
# Threads User Posts
Get a user's recent posts (their feed) on Threads by username. Returns post text, engagement metrics (likes, replies, reposts, quotes, reshares), author metadata, attached media, link previews, and whether each post is pinned to the profile.
## Endpoint
```
GET /v1/threads/user/posts
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Threads username, with or without leading @ (max 100 characters) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of the user's recent posts |
| `posts[].title` | string | Post title (format: @username on Threads) |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time (UTC, YYYY-MM-DD HH:MM:SS) |
| `posts[].author` | string | Author's Threads username |
| `posts[].source` | string | `"Threads"` |
| `posts[].domain` | string | `"threads.com"` |
| `posts[].snippet` | string | Post text content |
| `posts[].likes` | integer | Number of likes |
| `posts[].replies` | integer | Number of replies |
| `posts[].reposts` | integer | Number of reposts |
| `posts[].quotes` | integer | Number of quote posts |
| `posts[].reshares` | integer | Number of times reshared to other surfaces |
| `posts[].author_name` | string | Author's display name |
| `posts[].author_verified` | boolean | Whether the author is verified |
| `posts[].is_reply` | boolean | Whether the post is a reply |
| `posts[].is_pinned` | boolean | Whether the post is pinned to the top of the user's profile |
| `posts[].media_type` | string | Post type: `text`, `image`, `video`, or `carousel` |
| `posts[].image_url` | string | Cover image URL for image/video/carousel posts, empty for text-only (temporary; valid ~6-24 hours) |
| `posts[].video_url` | string | Direct video URL for video posts, empty otherwise (temporary; valid ~6-24 hours) |
| `posts[].width` | integer | Media width in pixels (0 when not applicable) |
| `posts[].height` | integer | Media height in pixels (0 when not applicable) |
| `posts[].has_audio` | boolean | Whether the post's video has audio |
| `posts[].reply_control` | string | Who can reply (e.g. `everyone`) |
| `posts[].hashtags` | array | Hashtags used in the post |
| `posts[].mentions` | array | Usernames mentioned in the post |
| `posts[].carousel_media` | array | Slides for carousel posts (`media_id`, `is_video`, `image_url`, `video_url`, `width`, `height`); empty otherwise |
| `posts[].link_preview` | object \| null | Link preview for posts sharing a URL (`url`, `display_url`, `title`, `description`, `image_url`, `favicon_url`), or null |
| `posts[].quoted_post` | object \| null | The embedded quoted/reposted post (same post shape), or null |
| `posts[].post_id` | string | Threads post ID |
| `posts[].code` | string | Post shortcode (used in the post URL) |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/threads/user/posts?username=mrbeast" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/threads/user/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "mrbeast"}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@mrbeast on Threads",
"url": "https://www.threads.com/@mrbeast/post/DPb1G6SEocH",
"date": "2025-10-05 16:49:10",
"author": "mrbeast",
"source": "Threads",
"domain": "threads.com",
"snippet": "When AI videos are just as good as normal videos, I wonder what that will do to the millions of creators making content for a living.",
"likes": 9742,
"replies": 1825,
"reposts": 297,
"quotes": 40,
"reshares": 105,
"author_name": "MrBeast",
"author_verified": true,
"is_reply": false,
"is_pinned": false,
"media_type": "text",
"image_url": "",
"video_url": "",
"width": 0,
"height": 0,
"has_audio": false,
"reply_control": "everyone",
"hashtags": [],
"mentions": [],
"carousel_media": [],
"link_preview": null,
"quoted_post": null,
"post_id": "3736813887196137223",
"code": "DPb1G6SEocH"
}
],
"count": 25
}
```
## Notes
- Each request returns a single page of the user's most recent posts, newest first.
---
# Truth Social User Posts
Get a user's recent posts (their feed) by username. Returns post text, engagement metrics (replies, reposts, likes), media attachments, hashtags, and reply status. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/truthsocial/user/posts
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | Yes | Truth Social username, with or without leading `@` (max 100 characters). |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1). Each page returns up to 20 posts. |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of the user's recent posts |
| `posts[].title` | string | Post title (format: `@username on Truth Social`) |
| `posts[].url` | string | Direct link to the post |
| `posts[].date` | string | Publication date and time |
| `posts[].author` | string | Truth Social username |
| `posts[].source` | string | `"Truth Social"` |
| `posts[].domain` | string | `"truthsocial.com"` |
| `posts[].snippet` | string | Post text with formatting removed |
| `posts[].likes` | integer | Number of likes |
| `posts[].replies` | integer | Number of replies |
| `posts[].reposts` | integer | Number of reposts |
| `posts[].post_id` | string | Truth Social post ID |
| `posts[].content_html` | string | Original post body as HTML, with links and mentions preserved |
| `posts[].media` | array | Media attachments, each with `media_id`, `type` (e.g. `image`, `video`), `url`, and `description` |
| `posts[].hashtags` | string[] | Hashtags used in the post |
| `posts[].language` | string | Detected language code (empty when not detected) |
| `posts[].visibility` | string | Post visibility (e.g. `public`) |
| `posts[].sensitive` | boolean | Whether the post is marked sensitive |
| `posts[].spoiler_text` | string | Content warning text (empty when none) |
| `posts[].sponsored` | boolean | Whether the post is sponsored |
| `posts[].is_reply` | boolean | Whether the post is a reply to another post |
| `posts[].in_reply_to_id` | string | ID of the post being replied to (empty when not a reply) |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `username` | string | The username the feed was fetched for |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/truthsocial/user/posts?username=realDonaldTrump&pages=2" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/truthsocial/user/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"username": "realDonaldTrump",
"pages": 2
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"title": "@realDonaldTrump on Truth Social",
"url": "https://truthsocial.com/@realDonaldTrump/117043133534824966",
"date": "2026-08-05 13:28:05",
"author": "realDonaldTrump",
"source": "Truth Social",
"domain": "truthsocial.com",
"snippet": "Thank you for your attention to this matter! President DJT",
"likes": 5514,
"replies": 567,
"reposts": 1399,
"post_id": "117043133534824966",
"content_html": "Thank you for your attention to this matter! President DJT
",
"media": [
{
"media_id": "117041192378469520",
"type": "video",
"url": "https://static-assets-1.truthsocial.com/media_attachments/files/117/041/192/original/9cbc020383d40cd5.mp4",
"description": ""
}
],
"hashtags": [],
"language": "en",
"visibility": "public",
"sensitive": false,
"spoiler_text": "",
"sponsored": false,
"is_reply": false,
"in_reply_to_id": ""
}
],
"username": "realDonaldTrump",
"pages": 2,
"count": 40
}
```
## Notes
- Posts are returned newest first, up to 20 per page. Use `pages` (1-10) to fetch more in a single call; you are billed per page requested.
- A user's feed can include their original posts and their replies. Use `is_reply` to distinguish them.
- `snippet` is the post text with formatting stripped. Use `content_html` when you need the original links and mentions.
---
# TikTok Videos
Search TikTok videos by keyword. Returns video title, URL, engagement metrics (plays, likes, comments, shares, downloads), author metadata, music info, and publication date. Supports filtering by time period and region, and fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/tiktok/videos
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
| `region` | No | 2-letter region code (e.g. `us`, `gb`, `jp`) |
| `publish_time` | No | Time filter: `0`=ALL, `1`=24h, `7`=week, `30`=month, `90`=3months, `180`=6months (default: 0) |
| `sort_by` | No | Sort order: `relevance`, `most_recent`, `most_liked` (default: relevance) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per page to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `videos` | array | Array of matching TikTok videos |
| `videos[].title` | string | Video title/caption |
| `videos[].url` | string | Direct link to the video |
| `videos[].date` | string | Publication date and time |
| `videos[].author` | string | TikTok username |
| `videos[].source` | string | `"TikTok"` |
| `videos[].domain` | string | `"tiktok.com"` |
| `videos[].snippet` | string | Video caption text |
| `videos[].play_count` | integer | Number of plays/views |
| `videos[].likes` | integer | Number of likes |
| `videos[].comments` | integer | Number of comments |
| `videos[].shares` | integer | Number of shares |
| `videos[].downloads` | integer | Number of downloads |
| `videos[].duration` | integer | Video duration in seconds |
| `videos[].is_ad` | boolean | Whether the video is an ad |
| `videos[].author_name` | string | Author's display name |
| `videos[].author_avatar` | string | Author's avatar URL |
| `videos[].cover` | string | Video cover/thumbnail URL |
| `videos[].music_title` | string | Title of the music used |
| `videos[].music_author` | string | Author of the music used |
| `videos[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `videos[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `videos[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `videos[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `videos[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/tiktok/videos?query=cooking&pages=2®ion=us&sort_by=relevance" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/tiktok/videos",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "cooking",
"pages": 2,
"region": "us",
"sort_by": "relevance"
}
)
print(response.json())
```
## Example Response
```json
{
"videos": [
{
"title": "Easy pasta recipe you need to try #cooking #recipe",
"url": "https://www.tiktok.com/@chefmike/video/7312345678901234567",
"date": "2026-02-20 18:45:30",
"author": "chefmike",
"source": "TikTok",
"domain": "tiktok.com",
"snippet": "Easy pasta recipe you need to try #cooking #recipe",
"play_count": 2450000,
"likes": 185000,
"comments": 3200,
"shares": 12500,
"downloads": 8400,
"duration": 45,
"is_ad": false,
"author_name": "Chef Mike",
"author_avatar": "https://p16-sign.tiktokcdn.com/...",
"cover": "https://p16-sign.tiktokcdn.com/...",
"music_title": "original sound",
"music_author": "chefmike",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"pages": 2,
"count": 20
}
```
---
# TikTok Users
Search TikTok users by keyword. Returns username, nickname, bio, follower/following counts, total likes, video count, and verification status. Supports fetching multiple pages in a single API call.
## Endpoint
```
GET /v1/tiktok/users
```
**Price:** $0.006 per page
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `users` | array | Array of matching user profiles |
| `users[].username` | string | TikTok username (unique ID) |
| `users[].nickname` | string | Display name |
| `users[].user_id` | string | TikTok user ID |
| `users[].bio` | string | Profile bio / signature |
| `users[].verified` | boolean | Whether the user is verified |
| `users[].is_private` | boolean | Whether the account is private |
| `users[].followers` | integer | Number of followers |
| `users[].following` | integer | Number of accounts followed |
| `users[].likes` | integer | Total likes received |
| `users[].video_count` | integer | Number of videos posted |
| `users[].avatar` | string | URL to profile picture |
| `users[].url` | string | Link to the profile |
| `pages` | integer | Number of pages fetched |
| `count` | integer | Total results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/tiktok/users?query=cooking&pages=1" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/tiktok/users",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "cooking",
"pages": 1
}
)
print(response.json())
```
## Example Response
```json
{
"users": [
{
"username": "cookingwithshereen",
"nickname": "Shereen Pavlides",
"user_id": "6812601268610257926",
"bio": "Chef | Author | TV Host",
"verified": true,
"is_private": false,
"followers": 483313,
"following": 47,
"likes": 3090163,
"video_count": 728,
"avatar": "https://p16-sign.tiktokcdn-us.com/.../photo.webp",
"url": "https://www.tiktok.com/@cookingwithshereen"
}
],
"pages": 1,
"count": 30
}
```
---
# TikTok User Profile
Get the full profile for a single TikTok user by username, user ID, or profile URL. Returns bio, bio link, follower / following counts, total likes, video count, verification status, join date, and linked Instagram, X/Twitter, and YouTube accounts.
## Endpoint
```
GET /v1/tiktok/user
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
Provide exactly one of `username`, `user_id`, or `url`.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `username` | One required | TikTok username, with or without leading `@` (max 100 characters) |
| `user_id` | One required | Numeric TikTok user ID, as returned by [Search Users](/docs/tiktok-users) |
| `url` | One required | TikTok profile URL, e.g. `https://www.tiktok.com/@tiktok` (max 500 characters) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `user` | object | Profile data |
| `user.username` | string | TikTok username (unique ID) |
| `user.nickname` | string | Display name |
| `user.user_id` | string | TikTok user ID |
| `user.sec_uid` | string | TikTok secondary user ID (secUid) |
| `user.bio` | string | Profile bio / signature |
| `user.bio_link` | string | Link displayed on the profile, or empty string |
| `user.verified` | boolean | Whether the user is verified |
| `user.is_private` | boolean | Whether the account is private |
| `user.followers` | integer | Number of followers |
| `user.following` | integer | Number of accounts followed |
| `user.likes` | integer | Total likes received |
| `user.video_count` | integer | Number of videos posted |
| `user.videos_liked` | integer | Number of videos the user has liked (0 when their liked list is private) |
| `user.avatar` | string | URL to profile picture |
| `user.avatar_hd` | string | URL to high-resolution profile picture |
| `user.date_joined` | string | Date and time the account was created |
| `user.date_joined_timestamp` | integer/null | Unix timestamp of the account creation date |
| `user.instagram_username` | string | Linked Instagram username, or empty string |
| `user.twitter_id` | string | Linked X/Twitter account ID, or empty string |
| `user.youtube_channel_id` | string | Linked YouTube channel ID, or empty string |
| `user.youtube_channel_title` | string | Linked YouTube channel name, or empty string |
| `user.url` | string | Link to the profile |
If the user does not exist, the endpoint returns a `404` with `code: "not_found"`.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/tiktok/user?username=gordonramsayofficial" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/tiktok/user",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"username": "gordonramsayofficial"}
)
print(response.json())
```
You can also pass a profile URL or a numeric user ID instead of a username:
```bash
curl "https://apidirect.io/v1/tiktok/user?url=https://www.tiktok.com/@gordonramsayofficial" \
-H "X-API-Key: YOUR_API_KEY"
```
## Example Response
```json
{
"user": {
"username": "gordonramsayofficial",
"nickname": "Gordon Ramsay",
"user_id": "6747935906352907269",
"sec_uid": "MS4wLjABAAAAv3zolJLlWp-WbKXqSZwVSflDdwcbjPADRG-dhb68k30dQjkFpkRs4HiMvWeeIyVv",
"bio": "I cook sometimes too.....",
"bio_link": "GordonRamsay.com/",
"verified": true,
"is_private": false,
"followers": 40817126,
"following": 573,
"likes": 728577233,
"video_count": 839,
"videos_liked": 0,
"avatar": "https://p19-common-sign.tiktokcdn-us.com/.../photo.webp",
"avatar_hd": "https://p19-common-sign.tiktokcdn-us.com/.../photo_1080.webp",
"date_joined": "2019-10-18 17:42:11",
"date_joined_timestamp": 1571420531,
"instagram_username": "",
"twitter_id": "",
"youtube_channel_id": "",
"youtube_channel_title": "",
"url": "https://www.tiktok.com/@gordonramsayofficial"
}
}
```
---
# TikTok Video Details
Get full details for a single TikTok video by URL or video ID. Returns the caption, play / like / comment / share / save counts, watermark-free playback and download URLs, cover images, music track info, and author details.
## Endpoint
```
GET /v1/tiktok/video
```
**Price:** $0.006 per request
**Free tier:** 50 requests/month
## Parameters
Provide exactly one of `url` or `video_id`.
| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | One required | TikTok video URL, e.g. `https://www.tiktok.com/@tiktok/video/7516594811734854943` (max 500 characters) |
| `video_id` | One required | Numeric TikTok video ID, as returned by [Search Videos](/docs/tiktok-videos) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `video` | object | Video data |
| `video.video_id` | string | TikTok video ID |
| `video.url` | string | Link to the video |
| `video.title` | string | Video caption |
| `video.region` | string | 2-letter region code the video was posted from |
| `video.date` | string | Date and time the video was published |
| `video.date_timestamp` | integer/null | Unix timestamp of the publish date |
| `video.duration` | integer | Video length in seconds |
| `video.play_count` | integer | Number of plays |
| `video.likes` | integer | Number of likes |
| `video.comments` | integer | Number of comments |
| `video.shares` | integer | Number of shares |
| `video.downloads` | integer | Number of downloads |
| `video.saves` | integer | Number of times the video was saved / favorited |
| `video.is_ad` | boolean | Whether the video is a paid ad |
| `video.cover` | string | URL to the video cover image |
| `video.dynamic_cover` | string | URL to the animated cover image |
| `video.origin_cover` | string | URL to the original still cover frame |
| `video.video_url` | string | Watermark-free MP4 URL (temporary signed link) |
| `video.video_url_hd` | string | Original-quality MP4 URL (temporary signed link), or empty string |
| `video.video_url_watermarked` | string | Watermarked MP4 URL (temporary signed link) |
| `video.size` | integer | File size of the watermark-free MP4 in bytes |
| `video.size_hd` | integer | File size of the original-quality MP4 in bytes |
| `video.size_watermarked` | integer | File size of the watermarked MP4 in bytes |
| `video.author` | string | Author's TikTok username |
| `video.author_name` | string | Author's display name |
| `video.author_id` | string | Author's TikTok user ID |
| `video.author_avatar` | string | URL to the author's profile picture |
| `video.author_url` | string | Link to the author's profile |
| `video.music_id` | string | TikTok ID of the music track |
| `video.music_title` | string | Music track title |
| `video.music_author` | string | Music track artist / creator |
| `video.music_url` | string | MP3 URL for the music track (temporary signed link) |
| `video.music_cover` | string | URL to the music track's cover image |
| `video.music_album` | string | Album name, or empty string |
| `video.music_original` | boolean | Whether the track is an original sound |
| `video.music_duration` | integer | Music track length in seconds |
| `video.mentioned_user_ids` | array | User IDs of accounts mentioned in the caption |
If the video does not exist, the endpoint returns a `404` with `code: "not_found"`.
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/tiktok/video?url=https://www.tiktok.com/@tiktok/video/7516594811734854943" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/tiktok/video",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"url": "https://www.tiktok.com/@tiktok/video/7516594811734854943"}
)
print(response.json())
```
You can also pass a numeric video ID instead of a URL:
```bash
curl "https://apidirect.io/v1/tiktok/video?video_id=7516594811734854943" \
-H "X-API-Key: YOUR_API_KEY"
```
## Example Response
```json
{
"video": {
"video_id": "7516594811734854943",
"url": "https://www.tiktok.com/@tiktok/video/7516594811734854943",
"title": "🌈🐬🦄 life after @Zara Larsson Symphony vocals 🌈🐬🦄",
"region": "US",
"date": "2025-06-16 17:07:10",
"date_timestamp": 1750093630,
"duration": 66,
"play_count": 18912653,
"likes": 879920,
"comments": 4382,
"shares": 17420,
"downloads": 1003,
"saves": 38685,
"is_ad": true,
"cover": "https://p16-common-sign.tiktokcdn-us.com/.../cover.jpeg",
"dynamic_cover": "https://p16-common-sign.tiktokcdn-us.com/.../dynamic.image",
"origin_cover": "https://p16-common-sign.tiktokcdn-us.com/.../origin.webp",
"video_url": "https://v16m.tiktokcdn-us.com/.../video.mp4",
"video_url_hd": "https://v16.tokcdn.com/.../7516594811734854943_original.mp4",
"video_url_watermarked": "https://v16m.tiktokcdn-us.com/.../video_wm.mp4",
"size": 7786703,
"size_hd": 38711004,
"size_watermarked": 7988034,
"author": "tiktok",
"author_name": "TikTok",
"author_id": "107955",
"author_avatar": "https://p19-common-sign.tiktokcdn-us.com/.../avatar.jpeg",
"author_url": "https://www.tiktok.com/@tiktok",
"music_id": "7516599978421209887",
"music_title": "original sound - tiktok",
"music_author": "TikTok",
"music_url": "https://v16-ies-music.tiktokcdn-us.com/.../audio.mp3",
"music_cover": "https://p16-common-sign.tiktokcdn-us.com/.../music.jpeg",
"music_album": "",
"music_original": true,
"music_duration": 66,
"mentioned_user_ids": ["205879097384816641"]
}
}
```
## Notes
- `video_url`, `video_url_hd`, `video_url_watermarked`, and `music_url` are temporary signed CDN links that expire after a few hours. Request the video again whenever you need fresh links.
- `video_url_hd` is the original upload quality and is usually a much larger file (see `size_hd`).
---
# Web Search
Search the web and get Google organic search results in real time. Returns title, URL, snippet, source and domain for each result. Supports country/language targeting, time filters, city-level geo, and an optional Google AI Overview.
## Endpoint
```
GET /v1/web/search
```
**Price:** $0.004 per page (+$0.002 flat per request when `include_ai_overview=true`)
**Free tier:** 50 requests/month
A "page" is 10 results. Each page you request consumes one billable request, so `pages=3` is billed as 3 requests.
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters). Supports Google advanced operators (`site:`, `inurl:`, `intitle:`, etc.) |
| `pages` | No | Number of result pages to fetch, 1-10 (default: 1). 10 results per page |
| `country` | No | 2-letter ISO 3166-1 alpha-2 country code (default: `us`) |
| `language` | No | 2-letter ISO 639-1 language code (default: `en`) |
| `time` | No | Time filter: `any`, `hour`, `day`, `week`, `month`, `year` (default: `any`) |
| `location` | No | City-level geo location (e.g. `London,England,United Kingdom`) |
| `device` | No | `desktop` or `mobile` (default: `desktop`) |
| `include_ai_overview` | No | When `true`, include Google AI Overview if available. Adds $0.002 flat to the request, regardless of how many pages you request |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `results` | array | Array of organic search results across all requested pages |
| `results[].position` | integer | Position on the result page |
| `results[].rank` | integer | Overall rank across the merged result set |
| `results[].title` | string | Result title |
| `results[].url` | string | Result URL |
| `results[].snippet` | string | Result snippet |
| `results[].source` | string | Result source name |
| `results[].domain` | string | Result domain |
| `results[].displayed_link` | string | Breadcrumb-style URL as displayed in the SERP |
| `pages` | integer | Number of pages requested |
| `count` | integer | Total results returned |
| `ai_overview` | object \| null | AI Overview content (only present when `include_ai_overview=true`). May be `null` if no overview was generated for this query |
| `ai_overview.text_parts` | array | Ordered list of overview parts (`paragraph`, `heading`, `list`, etc.) |
| `ai_overview.reference_links` | array | Citation links backing the overview |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/web/search?query=how%20to%20build%20a%20website&pages=2&country=us&language=en" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/web/search",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "how to build a website",
"pages": 2,
"country": "us",
"language": "en",
"include_ai_overview": "true"
}
)
print(response.json())
```
## Example Response
```json
{
"results": [
{
"position": 1,
"rank": 1,
"title": "Website Builder - Create a Free Website",
"url": "https://www.canva.com/website-builder/",
"snippet": "Design and launch a professional, one-of-a-kind website in minutes...",
"source": "Canva",
"domain": "canva.com",
"displayed_link": "https://www.canva.com › website-builder"
},
{
"position": 2,
"rank": 2,
"title": "Wix.com: Website Builder - Create a Free Website In Minutes",
"url": "https://www.wix.com/",
"snippet": "Get everything you need to create your website, your way...",
"source": "Wix",
"domain": "wix.com",
"displayed_link": "https://www.wix.com"
}
],
"pages": 2,
"count": 20,
"ai_overview": {
"text_parts": [
{
"type": "paragraph",
"text": "Building a website involves choosing a platform, designing pages, and publishing. Most modern builders offer drag-and-drop interfaces..."
}
],
"reference_links": [
{
"title": "How to Create a Website From Scratch",
"link": "https://www.wix.com/blog/how-to-build-website-from-scratch-guide",
"source": "Wix"
}
]
}
}
```
## Notes
- `pages` is a count, not a page number. `pages=3` returns the first 30 results merged into a single `results` array.
- AI Overviews are only returned when Google generates one for the query. Even with `include_ai_overview=true`, expect `ai_overview` to be `null` for some queries. The $0.002 surcharge applies whenever the flag is set.
- Use the `location` parameter to simulate searches from a specific city. Common formats include `City,State,Country` (e.g., `New York,New York,United States`).
---
# News Articles
Search news articles from thousands of sources worldwide. Returns article title, URL, snippet, author, source, and publication date. Supports filtering by time period, source, country, and language.
## Endpoint
```
GET /v1/news/articles
```
**Price:** $0.008 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `limit` | No | Number of results to return, 1-100 (default: 10) |
| `time_published` | No | Time filter: `anytime`, `1h`, `1d`, `7d`, `1y` (default: `anytime`) |
| `source` | No | Filter by news source (e.g., `bbc.com`) |
| `country` | No | 2-letter country code (default: `us`) |
| `language` | No | 2-letter language code (default: `en`) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `articles` | array | Array of matching news articles |
| `articles[].title` | string | Article headline |
| `articles[].url` | string | Direct link to the article |
| `articles[].snippet` | string | Article content preview |
| `articles[].photo_url` | string | Article photo URL |
| `articles[].thumbnail_url` | string | Article thumbnail URL |
| `articles[].published_datetime_utc` | string | Publication date and time in UTC |
| `articles[].authors` | array | List of author names |
| `articles[].source_url` | string | News source URL |
| `articles[].source_name` | string | News source name |
| `articles[].source_favicon_url` | string | News source favicon URL |
| `articles[].domain` | string | Article domain name |
| `limit` | integer | Requested result limit |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/news/articles?query=artificial%20intelligence&limit=10&time_published=1d&country=us&language=en" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/news/articles",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "artificial intelligence",
"limit": 10,
"time_published": "1d",
"country": "us",
"language": "en"
}
)
print(response.json())
```
## Example Response
```json
{
"articles": [
{
"title": "New AI Breakthrough Changes the Industry",
"url": "https://example.com/article/ai-breakthrough",
"snippet": "Researchers have announced a major advancement in artificial intelligence...",
"photo_url": "https://example.com/images/ai-photo.jpg",
"thumbnail_url": "https://example.com/images/ai-thumb.jpg",
"published_datetime_utc": "2025-01-15 14:30:00",
"authors": ["Jane Smith", "John Doe"],
"source_url": "https://example.com",
"source_name": "Example News",
"source_favicon_url": "https://example.com/favicon.ico",
"domain": "example.com"
}
],
"limit": 10,
"count": 1
}
```
---
# Forum Posts
Search forum posts across discussion boards, Q&A sites, and community forums. Returns post title, URL, source domain, and content snippet. Supports filtering by time period and country.
## Endpoint
```
GET /v1/forums/posts
```
**Price:** $0.008 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters) |
| `page` | No | Page number for pagination (default: 1) |
| `time` | No | Time filter: `any`, `hour`, `day`, `week`, `month`, `year` (default: `any`) |
| `country` | No | ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`, `DE`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis (Plutchik's Wheel) to each result. Adds +$0.001 per request to the cost. Returns emotion scores, dominant emotion, intensity, and polarity. |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `posts` | array | Array of matching forum posts |
| `posts[].position` | integer | Result ranking position |
| `posts[].rank` | integer | Result rank value |
| `posts[].title` | string | Post or thread title |
| `posts[].url` | string | Direct link to the post |
| `posts[].source` | string | Source name or forum domain |
| `posts[].domain` | string | Forum domain name |
| `posts[].snippet` | string | Post content preview |
| `posts[].sentiment` | object/null | Emotion analysis results. Only present when `get_sentiment=true`. Returns `null` if analysis fails. |
| `posts[].sentiment.emotions` | object | Plutchik emotion scores (0-100) for: `joy`, `trust`, `fear`, `surprise`, `sadness`, `disgust`, `anger`, `anticipation`. |
| `posts[].sentiment.dominant_emotion` | string | The emotion with the highest score. |
| `posts[].sentiment.emotional_intensity` | integer | Overall emotional intensity on a scale of 0-10. |
| `posts[].sentiment.polarity` | string | Overall sentiment polarity: `positive`, `negative`, or `neutral`. |
| `page` | integer | Current page number |
| `count` | integer | Number of results returned |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/forums/posts?query=programming&time=week&country=US" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/forums/posts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "programming",
"time": "week",
"country": "US"
}
)
print(response.json())
```
## Example Response
```json
{
"posts": [
{
"position": 1,
"rank": 1,
"title": "Discussion about programming",
"url": "https://forum.example.com/thread/...",
"source": "forum.example.com",
"domain": "forum.example.com",
"snippet": "Forum post content...",
"sentiment": {
"emotions": {
"joy": 40,
"trust": 55,
"fear": 0,
"surprise": 10,
"sadness": 0,
"disgust": 0,
"anger": 0,
"anticipation": 30
},
"dominant_emotion": "trust",
"emotional_intensity": 5,
"polarity": "positive"
}
}
],
"page": 1,
"count": 10
}
```
---
# Google AI Mode
Send a prompt to Google's AI Mode and get a structured conversational reply with citation links. Each response includes a `session_token` you can pass to the next call to continue the conversation with prior context.
## Endpoint
```
GET /v1/web/ai-mode
POST /v1/web/ai-mode
```
Both methods accept the same parameters. `GET` takes them as query parameters; `POST` takes them as a JSON body. Use `POST` for long prompts that don't fit comfortably in a URL.
**Price:** $0.005 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | The AI Mode prompt (max 12000 characters) |
| `country` | No | 2-letter ISO 3166-1 alpha-2 country code (default: `us`) |
| `language` | No | 2-letter ISO 639-1 language code (default: `en`) |
| `session_token` | No | Token from a previous response to continue the conversation in context |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `reply_parts` | array | Ordered list of structured reply parts. Render them in order to display the answer |
| `reply_parts[].type` | string | Part type: `paragraph`, `heading`, `list`, or `images` |
| `reply_parts[].text` | string | Text content. Present on `paragraph` and `heading` parts |
| `reply_parts[].ordered` | boolean | Present on `list` parts. `true` for numbered lists, `false` for bulleted |
| `reply_parts[].list` | array | Present on `list` parts. Each item is `{title, text}` |
| `reply_parts[].images` | array | Present on `images` parts. Each item is `{url, label, width, height}` |
| `reference_links` | array | Citation sources used in the reply |
| `reference_links[].title` | string | Citation title |
| `reference_links[].link` | string | Citation URL |
| `reference_links[].snippet` | string | Short preview of the cited source |
| `reference_links[].source` | string | Source name |
| `reference_links[].favicon` | string | Source favicon URL |
| `reference_links[].date` | string | Publication date (when available) |
| `session_token` | string | Token to pass in a subsequent request to continue this conversation |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/web/ai-mode?prompt=How%20do%20I%20make%20pizza%3F" \
-H "X-API-Key: YOUR_API_KEY"
```
Or with POST (recommended for long prompts):
```bash
curl -X POST "https://apidirect.io/v1/web/ai-mode" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "How do I make pizza?"}'
```
### Python
```python
import requests
# First call - new conversation
response = requests.get(
"https://apidirect.io/v1/web/ai-mode",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"prompt": "How do I make pizza?"}
)
data = response.json()
# Walk the reply_parts to display the answer
for part in data["reply_parts"]:
if part["type"] in ("paragraph", "heading"):
print(part["text"])
elif part["type"] == "list":
for item in part["list"]:
print(f"- {item['title']} {item['text']}")
# Follow-up that continues the same conversation
followup = requests.get(
"https://apidirect.io/v1/web/ai-mode",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"prompt": "What about a gluten-free version?",
"session_token": data["session_token"]
}
)
```
## Example Response
```json
{
"reply_parts": [
{
"type": "paragraph",
"text": "Making pizza at home involves preparing the dough, sauce, and toppings, then baking at high heat."
},
{
"type": "heading",
"text": "1. Prepare the Dough"
},
{
"type": "list",
"ordered": false,
"list": [
{
"title": "Activate Yeast:",
"text": "Mix warm water with yeast and a pinch of sugar. Let it sit for about 5-10 minutes until foamy."
},
{
"title": "Mix and Knead:",
"text": "Combine the yeast mixture with flour and salt. Knead for 5-10 minutes until smooth and elastic."
}
]
}
],
"reference_links": [
{
"title": "Best Homemade Pizza Dough (photo tutorial)",
"link": "https://www.crunchycreamysweet.com/the-best-homemade-pizza-dough-photo-tutorial/",
"snippet": "Instructions. Place water and sugar in a large mixing bowl...",
"source": "Crunchy Creamy Sweet",
"favicon": "https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.crunchycreamysweet.com&size=128",
"date": "Jul 6, 2012"
}
],
"session_token": "Q21vd1lUZHFaMjlNYWtOTWREQndWRmRyV1RNemFqRnViak01Ym1FeE1tdFZVemhFVGxCeFQxZE9RV1o0..."
}
```
## Notes
- `reply_parts` is an ordered array of typed blocks. Walk it in order and render each block based on its `type` field. This matches the structure used by the AI Overview inside `/v1/web/search`.
- Image blocks may include base64 placeholder URLs (`data:image/...`) alongside real CDN URLs — filter as needed.
- `session_token` is opaque — treat it as a string and pass it back unchanged to continue the conversation.
- Each follow-up call is billed as a fresh $0.005 request.
---
# Places Search
Search Google Maps places — local businesses, restaurants, hotels, shops and points of interest — by free-text query. Returns name, address, phone, website, rating, review count, opening hours, and coordinates for each result. Optionally bias results by geographic center.
## Endpoint
```
GET /v1/places/search
```
**Price:** $0.01 per page
**Free tier:** 20 requests/month
Each page returns up to 10 places.
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search keyword (max 500 characters). E.g. `coffee shops brooklyn`, `dentists 90210`, `hilton hotels paris` |
| `pages` | No | Number of pages to fetch, 1-20 (default: 1). Each page returns up to 10 results and is billed as one request |
| `lat` | No | Center latitude for geographic bias (provide with `lng`) |
| `lng` | No | Center longitude for geographic bias (provide with `lat`) |
| `zoom` | No | Map zoom level 1-20 (default: 13). Smaller values widen the search radius |
| `country` | No | 2-letter ISO 3166-1 alpha-2 region code (default: `us`) |
| `language` | No | 2-letter ISO 639-1 language code (default: `en`) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `places` | array | Array of matching places |
| `places[].place_id` | string | Google place_id (`ChIJ...`) |
| `places[].name` | string | Place display name |
| `places[].type` | string | Primary category (e.g. `Pizza restaurant`) |
| `places[].subtypes` | array | All Google categories |
| `places[].phone_number` | string \| null | Phone number in E.164 format |
| `places[].website` | string \| null | Official website URL |
| `places[].domain` | string \| null | Website apex domain (e.g. `joespizzanyc.com`) |
| `places[].rating` | number \| null | Average rating, 0.0–5.0 |
| `places[].review_count` | integer | Total number of reviews |
| `places[].reviews_per_rating` | object | Count of reviews per star (`{"1": N, "2": N, ...}`) |
| `places[].price_level` | string \| null | Price indicator (e.g. `$`, `$10–20`) |
| `places[].verified` | boolean | Whether the listing is verified by Google |
| `places[].business_status` | string | `OPEN`, `CLOSED_TEMPORARILY`, `CLOSED_PERMANENTLY` |
| `places[].opening_status` | string \| null | Human-readable status (e.g. `Open · Closes 3 AM`) |
| `places[].working_hours` | object \| null | Hours by day-of-week |
| `places[].opening_date` | string \| null | First listing date if known |
| `places[].address` | string | Full address |
| `places[].street_address` | string \| null | Street component only |
| `places[].district` | string \| null | District / neighborhood |
| `places[].city` | string \| null | City |
| `places[].state` | string \| null | State / region |
| `places[].zipcode` | string \| null | Postal code |
| `places[].country` | string \| null | Country code |
| `places[].latitude` | number | Latitude |
| `places[].longitude` | number | Longitude |
| `places[].timezone` | string \| null | IANA timezone (e.g. `America/New_York`) |
| `places[].summary` | string \| null | Short editorial summary |
| `places[].about` | object \| null | Structured About panel (`summary` plus a `details` object of categorised attributes) |
| `places[].photo_count` | integer | Total photos available |
| `places[].photos_sample` | array | Sample of recent photos (same shape as [Place Photos](/docs/places-photos) items) |
| `places[].place_link` | string | Google Maps URL |
| `places[].reviews_link` | string \| null | Google reviews URL |
| `places[].booking_link` | string \| null | Booking URL if available |
| `places[].reservations_link` | string \| null | Reservation URL if available |
| `places[].order_link` | string \| null | Online order URL if available |
| `places[].owner_name` | string \| null | Listing owner name |
| `places[].owner_link` | string \| null | Listing owner profile URL |
| `places[].cid` | string | Google CID identifier |
| `count` | integer | Number of places returned |
| `query` | string | Echo of the search query |
| `pages` | integer | Echo of the requested pages |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/places/search?query=pizza%20new%20york&pages=2" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/places/search",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"query": "pizza new york",
"pages": 2,
"lat": 40.7549,
"lng": -73.9870,
"zoom": 14,
}
)
print(response.json())
```
## Example Response
```json
{
"places": [
{
"place_id": "ChIJifIePKtZwokRVZ-UdRGkZzs",
"name": "Joe's Pizza Broadway",
"type": "Pizza restaurant",
"subtypes": ["Pizza restaurant", "Pizza delivery", "Restaurant"],
"phone_number": "+16465594878",
"website": "https://www.joespizzanyc.com",
"domain": "joespizzanyc.com",
"rating": 4.5,
"review_count": 25433,
"reviews_per_rating": {"1": 753, "2": 604, "3": 2107, "4": 4946, "5": 17023},
"price_level": "$10–20",
"verified": true,
"business_status": "OPEN",
"opening_status": "Open · Closes 3 AM",
"working_hours": {"Monday": ["10 AM–3 AM"], "Sunday": ["10 AM–3 AM"]},
"opening_date": null,
"address": "Joe's Pizza Broadway, 1435 Broadway, New York, NY 10018",
"street_address": "1435 Broadway",
"district": "Manhattan",
"city": "New York",
"state": "New York",
"zipcode": "10018",
"country": "US",
"latitude": 40.75468,
"longitude": -73.98703,
"timezone": "America/New_York",
"summary": "Modern outpost of a longtime counter-serve pizza joint prepping New York-style slices and pies.",
"about": {
"summary": "Modern outpost of a longtime counter-serve pizza joint prepping New York-style slices and pies.",
"details": {
"Accessibility": {
"Wheelchair accessible entrance": true,
"Wheelchair accessible parking lot": false,
"Wheelchair accessible seating": false
}
}
},
"photo_count": 22117,
"photos_sample": [
{
"photo_id": "CIABIhBpKlqRIOpwhdI384bUAF4L",
"type": "photo",
"photo_url": "https://lh3.googleusercontent.com/gps-cs-s/APNQkAH...",
"photo_url_large": "https://lh3.googleusercontent.com/gps-cs-s/APNQkAH...=w3000-h4000-k-no",
"video_thumbnail_url": null,
"latitude": 40.7546469,
"longitude": -73.9868158,
"photo_datetime_utc": "2026-06-16T00:00:00.000Z",
"photo_timestamp": 1781568000
}
],
"place_link": "https://www.google.com/maps/place/data=...",
"reviews_link": "https://search.google.com/local/reviews?placeid=ChIJifIePKtZwokRVZ-UdRGkZzs",
"booking_link": "https://www.google.com/searchviewer/42?...",
"reservations_link": "https://www.fooddiscoveryapp.com/new-york-city/joes-pizza",
"order_link": "https://www.google.com/searchviewer/42?...",
"owner_name": "Joe's Pizza Broadway",
"owner_link": "https://maps.google.com/maps/contrib/103877821925204408966",
"cid": "4280570365733019477"
}
],
"count": 1,
"query": "pizza new york",
"pages": 2
}
```
## Notes
- The `place_id` field is the standard Google identifier. Pass it to [Place Details](/docs/places-details), [Place Reviews](/docs/places-reviews) and [Place Photos](/docs/places-photos) to fetch more data about a result.
- When you provide `lat` and `lng`, results are biased to that area. Without coordinates, results use a default center; for accurate local results, always pass coordinates.
- The `zoom` level mirrors Google Maps zoom — `13` covers roughly a city, `15` a neighborhood, `10` a metro area.
---
# Place Details
Get full details for a single Google Maps place by `place_id`. Returns everything Places Search returns, plus Plus Codes, a menu link, and an `emails_and_contacts` scrape of the place's official website (emails, phone numbers and links to 10 social platforms).
## Endpoint
```
GET /v1/places/details
```
**Price:** $0.003 per request
**Free tier:** 50 requests/month
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `place_id` | Yes | Google `place_id` (e.g. `ChIJifIePKtZwokRVZ-UdRGkZzs`), as returned by the [Places Search](/docs/places-search) endpoint |
| `country` | No | 2-letter ISO 3166-1 alpha-2 region code (default: `us`) |
| `language` | No | 2-letter ISO 639-1 language code (default: `en`) |
## Response Fields
The `place` object has the same schema as items in [Places Search](/docs/places-search), plus the fields below.
| Field | Type | Description |
|-------|------|-------------|
| `place` | object | Full place object (see [Places Search](/docs/places-search) for the shared schema) |
| `place.global_plus_code` | string \| null | Global Plus Code (e.g. `87G8Q237+V5`) |
| `place.compound_plus_code` | string \| null | Compound Plus Code (e.g. `Q237+V5 New York`) |
| `place.menu_link` | string \| null | Menu URL if the place has one |
| `place.emails_and_contacts` | object | Scrape of the place's official website |
| `place.emails_and_contacts.emails` | array | Email addresses found on the site |
| `place.emails_and_contacts.phone_numbers` | array | Phone numbers found on the site (raw, not normalized to E.164) |
| `place.emails_and_contacts.facebook` | string \| null | Facebook profile URL |
| `place.emails_and_contacts.instagram` | string \| null | Instagram profile URL |
| `place.emails_and_contacts.linkedin` | string \| null | LinkedIn profile URL |
| `place.emails_and_contacts.twitter` | string \| null | Twitter/X profile URL |
| `place.emails_and_contacts.tiktok` | string \| null | TikTok profile URL |
| `place.emails_and_contacts.youtube` | string \| null | YouTube channel URL |
| `place.emails_and_contacts.pinterest` | string \| null | Pinterest profile URL |
| `place.emails_and_contacts.snapchat` | string \| null | Snapchat profile URL |
| `place.emails_and_contacts.yelp` | string \| null | Yelp listing URL |
| `place.emails_and_contacts.github` | string \| null | GitHub profile URL |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/places/details?place_id=ChIJifIePKtZwokRVZ-UdRGkZzs" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/places/details",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"place_id": "ChIJifIePKtZwokRVZ-UdRGkZzs"}
)
print(response.json())
```
## Example Response
```json
{
"place": {
"place_id": "ChIJifIePKtZwokRVZ-UdRGkZzs",
"name": "Joe's Pizza Broadway",
"type": "Pizza restaurant",
"subtypes": ["Pizza restaurant", "Pizza delivery", "Restaurant"],
"phone_number": "+16465594878",
"website": "https://www.joespizzanyc.com",
"domain": "joespizzanyc.com",
"rating": 4.5,
"review_count": 25433,
"reviews_per_rating": {"1": 753, "2": 604, "3": 2107, "4": 4946, "5": 17023},
"price_level": "$10–20",
"verified": true,
"business_status": "OPEN",
"opening_status": "Open · Closes 3 AM",
"working_hours": {"Monday": ["10 AM–3 AM"]},
"opening_date": null,
"address": "1435 Broadway, New York, NY 10018",
"street_address": "1435 Broadway",
"district": "Manhattan",
"city": "New York",
"state": "New York",
"zipcode": "10018",
"country": "US",
"latitude": 40.75468,
"longitude": -73.98703,
"timezone": "America/New_York",
"summary": "Modern outpost of a longtime counter-serve pizza joint prepping New York-style slices and pies.",
"about": {
"summary": "Modern outpost of a longtime counter-serve pizza joint prepping New York-style slices and pies.",
"details": {
"Accessibility": {
"Wheelchair accessible entrance": true,
"Wheelchair accessible parking lot": false,
"Wheelchair accessible seating": false
}
}
},
"photo_count": 22117,
"photos_sample": [
{
"photo_id": "CIABIhAViB6GuQB0Czq6u1UIyD60",
"type": "photo",
"photo_url": "https://lh3.googleusercontent.com/gps-cs-s/APNQkAH...",
"photo_url_large": "https://lh3.googleusercontent.com/gps-cs-s/APNQkAH...=w4280-h3407-k-no",
"video_thumbnail_url": null,
"latitude": 40.7546469,
"longitude": -73.9868158,
"photo_datetime_utc": "2026-05-30T00:00:00.000Z",
"photo_timestamp": 1780099200
}
],
"place_link": "https://www.google.com/maps/place/...",
"reviews_link": "https://search.google.com/local/reviews?placeid=ChIJifIePKtZwokRVZ-UdRGkZzs",
"booking_link": "https://www.google.com/searchviewer/42?...",
"reservations_link": "https://www.fooddiscoveryapp.com/new-york-city/joes-pizza",
"order_link": "https://www.google.com/searchviewer/42?...",
"owner_name": "Joe's Pizza Broadway",
"owner_link": "https://maps.google.com/maps/contrib/103877821925204408966",
"cid": "4280570365733019477",
"global_plus_code": "87G8Q237+V5",
"compound_plus_code": "Q237+V5 New York",
"menu_link": null,
"emails_and_contacts": {
"emails": [],
"phone_numbers": ["2123661182", "7183882216", "2122670860", "2123889474"],
"facebook": null,
"instagram": "https://www.instagram.com/joespizzanyc",
"linkedin": null,
"twitter": null,
"tiktok": null,
"youtube": null,
"pinterest": null,
"snapchat": null,
"yelp": null,
"github": null
}
}
}
```
## Notes
- The website scrape runs on every call and adds ~0.5–1s to the response time.
- If the site is unreachable or has no contact info, `emails_and_contacts` is returned with empty arrays and `null` social links.
- A 404 with `code: "not_found"` is returned when the `place_id` doesn't match any place; `not_found` responses are not charged.
---
# Place Reviews
Get user reviews for a place by `place_id`. Each review includes the rating, full review text, author info (with photo URL and total review count), timestamps, attached photos, and any owner response.
## Endpoint
```
GET /v1/places/reviews
```
**Price:** $0.01 per page
**Free tier:** 20 requests/month
Each page returns up to 10 reviews.
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `place_id` | Yes | Google `place_id`, as returned by the [Places Search](/docs/places-search) endpoint |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1). Each page returns up to 10 reviews and is billed as one request |
| `sort_by` | No | `most_relevant` (default), `newest`, `highest_ranking`, `lowest_ranking` |
| `language` | No | 2-letter ISO 639-1 language code (default: `en`). Returns only reviews originally written in this language |
| `translate_reviews` | No | Set to `true` to translate the returned reviews into the requested `language` |
| `country` | No | 2-letter ISO 3166-1 alpha-2 region code (default: `us`) |
| `get_sentiment` | No | Set to `true` to add AI emotion analysis to each review (+$0.001/request) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `reviews` | array | Array of reviews |
| `reviews[].review_id` | string | Stable review identifier |
| `reviews[].rating` | integer | Star rating, 1-5 |
| `reviews[].review_text` | string | Review body text |
| `reviews[].review_datetime_utc` | string | ISO 8601 review datetime (UTC) |
| `reviews[].review_timestamp` | integer | Unix timestamp (seconds) |
| `reviews[].review_time` | string | Human-readable relative time (e.g. `3 months ago`) |
| `reviews[].review_link` | string | Direct link to the review on Google Maps |
| `reviews[].review_photos` | array | Array of photo URLs attached to the review |
| `reviews[].review_language` | string | Detected review language code |
| `reviews[].review_text_translated_language` | string \| null | Target language code if the review has been translated |
| `reviews[].like_count` | integer | Number of "likes" the review has received |
| `reviews[].review_source` | string | Source platform name (typically `Google`) |
| `reviews[].review_source_logo` | string | Source platform logo URL |
| `reviews[].author_id` | string | Google contributor ID |
| `reviews[].author_name` | string | Review author display name |
| `reviews[].author_link` | string | Author Google Maps profile URL |
| `reviews[].author_photo_url` | string \| null | Author profile photo URL |
| `reviews[].author_review_count` | integer | Total reviews this author has posted |
| `reviews[].author_photo_count` | integer | Total photos this author has uploaded |
| `reviews[].author_reviews_link` | string | URL to all of this author's reviews |
| `reviews[].author_is_local_guide` | boolean | Whether the author is a Google Local Guide |
| `reviews[].author_local_guide_level` | integer \| null | Local Guide level (1-10) if applicable |
| `reviews[].owner_response` | object \| null | Object with `text`, `datetime_utc`, `timestamp`, `time`, `language` when the place owner has responded |
| `reviews[].sentiment` | object | Emotion analysis: `emotions`, `dominant_emotion`, `emotional_intensity`, `polarity` (when `get_sentiment=true`) |
| `count` | integer | Number of reviews returned |
| `pages` | integer | Echo of requested pages |
| `sort_by` | string | Echoed sort order |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/places/reviews?place_id=ChIJifIePKtZwokRVZ-UdRGkZzs&pages=2&sort_by=newest" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/places/reviews",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"place_id": "ChIJifIePKtZwokRVZ-UdRGkZzs",
"pages": 2,
"sort_by": "newest"
}
)
print(response.json())
```
## Example Response
```json
{
"reviews": [
{
"review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pWeU1rdFZhREZPY214dmRVSlplRzQ0ZURWVk9XYxAB",
"rating": 5,
"review_text": "Amazing pizza, fast service. Highly recommend.",
"review_datetime_utc": "2026-02-15T12:05:54.947Z",
"review_timestamp": 1771157154,
"review_time": "3 months ago",
"review_link": "https://www.google.com/maps/reviews/...",
"review_photos": ["https://lh3.googleusercontent.com/grass-cs/..."],
"review_language": "en",
"review_text_translated_language": "en",
"like_count": 0,
"review_source": "Google",
"review_source_logo": "https://www.gstatic.com/images/branding/product/1x/googleg_48dp.png",
"author_id": "103696814314978516852",
"author_name": "Salman Idrees",
"author_link": "https://www.google.com/maps/contrib/103696814314978516852",
"author_photo_url": "https://lh3.googleusercontent.com/a-/ALV-...",
"author_review_count": 392,
"author_photo_count": 356,
"author_reviews_link": "https://www.google.com/maps/contrib/103696814314978516852/reviews",
"author_is_local_guide": true,
"author_local_guide_level": 7,
"owner_response": null
}
],
"count": 1,
"pages": 2,
"sort_by": "newest"
}
```
## Getting more reviews
Beyond increasing the `pages` parameter, two knobs surface different review sets:
**1. `sort_by`** — four options, each returns a different set of reviews:
- `most_relevant` (default) — Google's relevance ranking
- `newest` — reverse chronological order
- `highest_ranking` — 5-star and 4-star reviews first
- `lowest_ranking` — 1-star and 2-star reviews first
**2. `language`** — filters reviews to those originally written in that language. The same `place_id` returns a different set of reviews for each language.
Combining all four sort orders with a handful of languages can surface several hundred reviews per place.
To consolidate the multilingual set in one language, add `translate_reviews=true` and the returned reviews will be translated into your chosen `language`.
## Notes
- If a place has no reviews in the requested `language`, the response is empty (still billed as one request).
- `translate_reviews=true` replaces each review's text with the translation. The `review_language` field shows the original language; `review_text_translated_language` matches your target.
- The `owner_response` field is `null` when the business owner has not replied to the review.
- Set `get_sentiment=true` to add per-review emotion analysis to the response.
---
# Place Photos
Get photos and videos for a place by `place_id`. Returns photo URLs (standard and high-resolution), capture coordinates, and timestamps.
## Endpoint
```
GET /v1/places/photos
```
**Price:** $0.01 per page
**Free tier:** 20 requests/month
Each page returns up to 10 photos.
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `place_id` | Yes | Google `place_id`, as returned by the [Places Search](/docs/places-search) endpoint |
| `pages` | No | Number of pages to fetch, 1-10 (default: 1). Each page returns up to 10 items and is billed as one request |
| `country` | No | 2-letter ISO 3166-1 alpha-2 region code (default: `us`) |
| `language` | No | 2-letter ISO 639-1 language code (default: `en`) |
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `photos` | array | Array of photos and videos. Filter on the `type` field if you only want one |
| `photos[].photo_id` | string | Stable photo identifier |
| `photos[].type` | string | `photo` or `video` |
| `photos[].photo_url` | string | Standard-resolution image URL |
| `photos[].photo_url_large` | string \| null | High-resolution image URL (typically 3000–4000px wide). `null` for items where no large variant exists (some videos and older photos) |
| `photos[].video_thumbnail_url` | string \| null | Video thumbnail URL (set only when `type` is `video`) |
| `photos[].latitude` | number \| null | Capture latitude |
| `photos[].longitude` | number \| null | Capture longitude |
| `photos[].photo_datetime_utc` | string | ISO 8601 capture datetime (UTC) |
| `photos[].photo_timestamp` | integer | Unix timestamp (seconds) |
| `count` | integer | Total photos returned |
| `pages` | integer | Echo of requested pages |
## Example Request
### cURL
```bash
curl "https://apidirect.io/v1/places/photos?place_id=ChIJifIePKtZwokRVZ-UdRGkZzs&pages=2" \
-H "X-API-Key: YOUR_API_KEY"
```
### Python
```python
import requests
response = requests.get(
"https://apidirect.io/v1/places/photos",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"place_id": "ChIJifIePKtZwokRVZ-UdRGkZzs",
"pages": 2,
}
)
data = response.json()
print(f"Got {data['count']} photos across {data['pages']} pages")
```
## Example Response
```json
{
"photos": [
{
"photo_id": "CIABIhAViB6GuQB0Czq6u1UIyD60",
"type": "photo",
"photo_url": "https://lh3.googleusercontent.com/gps-cs-s/APNQkAH...",
"photo_url_large": "https://lh3.googleusercontent.com/gps-cs-s/APNQkAH...=w4280-h3407-k-no",
"video_thumbnail_url": null,
"latitude": 40.7546469,
"longitude": -73.9868158,
"photo_datetime_utc": "2026-05-30T00:00:00.000Z",
"photo_timestamp": 1780099200
},
{
"photo_id": "CIHM0ogKEICAgICGgNfJ4wE",
"type": "video",
"photo_url": "https://lh3.googleusercontent.com/gps-cs-s/...",
"photo_url_large": null,
"video_thumbnail_url": "https://lh3.googleusercontent.com/gps-cs-s/...=w640-h360-k-no",
"latitude": 40.7546795,
"longitude": -73.9870291,
"photo_datetime_utc": "2021-11-16T00:00:00.000Z",
"photo_timestamp": 1637020800
}
],
"count": 20,
"pages": 2
}
```
## Notes
- `photo_url_large` is the full-resolution version of the photo. Some videos and older photos don't have a large variant — the field is `null` in that case.
- The `type` field is `"photo"` or `"video"`. Filter client-side if you only want one.
- Photos are typically returned newest-first based on upload date.
---
# Build with AI
If you're writing code with an AI assistant, you can skip the manual integration work. Connect your agent to the API Direct [MCP server](/docs/mcp-claude-code) and it can wire up endpoints for you directly.
## Why it works
The MCP server exposes every API Direct endpoint to your agent — including the exact input parameters and response structure for each one. Your assistant doesn't have to guess at the schema or read through docs page by page. It already has everything it needs to call an endpoint correctly and map the response into your code.
That means instead of integrating each endpoint by hand, you can describe what you want and let your agent do it in one shot.
## Example prompts
Once the MCP is connected, try asking your assistant things like:
- "Implement all of the TikTok endpoints in my codebase."
- "Add every Google search endpoint to my API client."
- "Create typed functions for each Reddit endpoint with proper response models."
- "Wire up the LinkedIn job search endpoint and render the results in my app."
Your agent will pull the correct parameters and response shapes from the MCP and generate the integration code for you.
## Getting started
1. Connect the MCP server in your tool of choice — [Claude Code](/docs/mcp-claude-code), [Cursor](/docs/mcp-cursor), [Claude Desktop](/docs/mcp-claude-desktop), or [ChatGPT](/docs/mcp-chatgpt).
2. Ask it to implement the endpoints you need.
3. Review the generated code and run it.
That's it — no copy-pasting schemas, no hand-writing request boilerplate.
---
# n8n
Use API Direct in your [n8n](https://n8n.io) workflows with our verified community node — search social media, news, and the web as a native workflow step, no code required.
The node is published on npm as [`n8n-nodes-apidirect`](https://www.npmjs.com/package/n8n-nodes-apidirect) and covers 58 operations across Twitter/X, Facebook, Instagram, TikTok, YouTube, Reddit, Threads, Truth Social, and Google (web search, AI Mode, news, forums, and Maps/Places).
## Install
API Direct is a [verified community node](https://docs.n8n.io/integrations/community-nodes/installation/verified-install/), so on n8n Cloud and current self-hosted versions there is nothing to install separately:
1. Open the nodes panel and search for **API Direct**.
2. Click it (or drag it onto the canvas) — n8n installs the node automatically.
If it doesn't appear in search, make sure **Verified Community Nodes** is enabled (Cloud: **Admin Panel**; self-hosted: **Settings → Community nodes**) and restart your instance.
On older self-hosted versions (1.94+) you can install it manually instead: open **Settings → Community nodes**, click **Install a community node**, enter `n8n-nodes-apidirect`, tick the acknowledgement, and click **Install**.
## Set up credentials
1. Get your API key from the [API Keys](https://apidirect.io/dashboard/keys) page — new accounts include $5 of free credit plus [50 free requests per endpoint per month](/docs/pricing).
2. In n8n, add the API Direct node to a workflow and choose **Create new credential**.
3. Paste your key (starts with `ak_live_`) and save.
n8n tests the connection automatically — you should see **"Connection tested successfully"**.
## Usage
Pick a **Resource** (the platform) and an **Operation**, fill in the required fields, and execute. Optional parameters — page counts, sort order, date filters, [sentiment analysis](/docs/pricing#emotion-analysis) — live under **Additional Fields → Add Field**.
List operations return one n8n item per result (20 tweets become 20 items), so you can feed results straight into filters, spreadsheets, Slack messages, or any other node. Detail operations return a single item.
A few things worth knowing:
- **Pagination** uses `Page` or `Pages` fields rather than cursors. Where the API fetches multiple pages server-side in one call, each page is billed as one request — the field description tells you when that applies. See [Pagination](/docs/pagination).
- **Pricing** is pay-as-you-go, $0.002–$0.01 per request — each operation's description shows its price. No subscriptions. See [Pricing](/docs/pricing).
- **Search operations** support [boolean search syntax](/docs/boolean-search).
## Use with AI Agents
The node is flagged as an AI Agent tool. Attach **API Direct** to an n8n AI Agent as a tool, and the agent can search any platform on demand — ask it *"What are people saying about our brand on Twitter this week?"* and it will pick the operation, run the search, and summarize the results.
## Troubleshooting
**"Authorization failed - please check your credentials"** — Double-check your API key in the [dashboard](https://apidirect.io/dashboard/keys). Keys start with `ak_live_`.
**"Payment required"** — Your credit balance is empty and the endpoint's free-tier allowance is used up. Top up on the [billing page](https://apidirect.io/dashboard/billing).
**"Service unavailable"** — The endpoint is temporarily suspended; check the [status page](https://apidirect.io/status).
**Node not in the panel after install** — Refresh the browser tab; on older n8n versions, restart the instance.
---
# Claude Code
Use API Direct as an MCP server in Claude Code to search social media and news directly from your terminal.
## Setup
Run this command, replacing `YOUR_API_KEY` with your key from the [API Keys](https://apidirect.io/dashboard/keys) page:
```bash
claude mcp add --transport http apidirect "https://apidirect.io/mcp?token=YOUR_API_KEY"
```
That's it. Claude Code can now search LinkedIn, Twitter/X, Facebook, Reddit, YouTube, Instagram, TikTok, forums, and news articles.
## Usage
Ask Claude Code to search any supported platform. For example:
- "Search LinkedIn for posts about AI agents"
- "Find recent Reddit discussions about React Server Components"
- "Search Twitter for posts about the latest OpenAI release"
- "Get @elonmusk's Twitter profile"
- "Show me the latest tweets from @OpenAI"
- "What's trending on Twitter right now?"
- "Find YouTube videos about MCP servers"
- "Search news for articles about climate policy"
Claude Code will automatically call the right tool and return results.
## Available Tools
All API Direct endpoints are available as MCP tools. This includes search across LinkedIn, Twitter/X, Facebook, Reddit, YouTube, Instagram, TikTok, forums, and news — as well as platform-specific tools for Twitter user profiles, Facebook pages/groups, and more. See the [endpoint documentation](/docs/linkedin-posts) for the full list.
## Removing the Server
```bash
claude mcp remove apidirect
```
## Troubleshooting
**"No API key provided"** — Make sure the `?token=` parameter is included in the URL.
**"Invalid API key"** — Double-check your API key in the [dashboard](https://apidirect.io/dashboard/keys). Keys start with `ak_live_`.
**"Rate limit exceeded"** — You've hit your plan's rate limit. Check your [usage](https://apidirect.io/dashboard) or upgrade your plan.
---
# Claude Desktop
Use API Direct as an MCP server in Claude Desktop to search social media and news from your conversations.
## Option 1: Connectors (Recommended)
1. Open Claude Desktop and go to **Settings** > **Connectors**
2. Click **Add custom connector**
3. Paste the following URL, replacing `YOUR_API_KEY` with your key from the [API Keys](https://apidirect.io/dashboard/keys) page:
```
https://apidirect.io/mcp?token=YOUR_API_KEY
```
4. Click **Add**
## Option 2: Config File
If you prefer manual configuration, add API Direct to your `claude_desktop_config.json`:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"apidirect": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://apidirect.io/mcp?token=YOUR_API_KEY"]
}
}
}
```
Replace `YOUR_API_KEY` with your key from the [API Keys](https://apidirect.io/dashboard/keys) page. Restart Claude Desktop after saving the file.
This option requires Node.js to be installed, as it uses `npx` to run the `mcp-remote` bridge.
## Usage
Once connected, ask Claude to search any supported platform:
- "Search LinkedIn for posts about AI agents"
- "Find recent Reddit discussions about React Server Components"
- "Search Twitter for posts about the latest OpenAI release"
Claude will ask for permission the first time it uses a tool, then return results inline.
## Available Tools
All API Direct endpoints are available as MCP tools. This includes search across LinkedIn, Twitter/X, Facebook, Reddit, YouTube, Instagram, TikTok, forums, and news — as well as platform-specific tools for Twitter user profiles, Facebook pages/groups, and more. See the [endpoint documentation](/docs/linkedin-posts) for the full list.
## Troubleshooting
**"No API key provided"** — Make sure the `?token=` parameter is included in the URL.
**"Invalid API key"** — Double-check your API key in the [dashboard](https://apidirect.io/dashboard/keys). Keys start with `ak_live_`.
**Tools not appearing** — Restart Claude Desktop after adding the connector or editing the config file.
**Config file option not working** — Make sure Node.js is installed (`node --version`). The `mcp-remote` package is fetched automatically via `npx`.
---
# ChatGPT
Use API Direct as an MCP server in ChatGPT to search social media and news from your conversations.
## Setup
1. Open ChatGPT and go to **Settings** > **Connectors**
2. Under **Advanced settings**, toggle **Developer Mode** on
3. Click **Create** and fill in:
- **Name:** API Direct
- **Description:** Search social media and news across LinkedIn, Twitter, Reddit, YouTube, Instagram, TikTok, Facebook, forums, and news articles.
- **Server URL:** the URL below, with your API key from the [API Keys](https://apidirect.io/dashboard/keys) page:
```
https://apidirect.io/mcp?token=YOUR_API_KEY
```
4. Click **Create**
## Usage
Once the app is created, just ask ChatGPT to search any platform in a new conversation:
- "Search LinkedIn for posts about AI agents"
- "Find recent Reddit discussions about React Server Components"
- "Search Twitter for posts about the latest OpenAI release"
ChatGPT will automatically use the API Direct tools and display the results.
## Available Tools
All API Direct endpoints are available as MCP tools. This includes search across LinkedIn, Twitter/X, Facebook, Reddit, YouTube, Instagram, TikTok, forums, and news — as well as platform-specific tools for Twitter user profiles, Facebook pages/groups, and more. See the [endpoint documentation](/docs/linkedin-posts) for the full list.
## Troubleshooting
**"No API key provided"** — Make sure the `?token=` parameter is included in the URL.
**"Invalid API key"** — Double-check your API key in the [dashboard](https://apidirect.io/dashboard/keys). Keys start with `ak_live_`.
**Developer Mode not available** — Check that your plan supports Developer Mode under **Settings** > **Connectors** > **Advanced settings**.
---
# Cursor
Use API Direct as an MCP server in Cursor to search social media and news from your editor.
## Setup
Create or edit `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"apidirect": {
"url": "https://apidirect.io/mcp?token=YOUR_API_KEY"
}
}
}
```
Replace `YOUR_API_KEY` with your key from the [API Keys](https://apidirect.io/dashboard/keys) page.
Cursor will detect the config automatically. You can also add this to your global Cursor settings to make it available in all projects.
## Usage
In Cursor's AI chat, ask it to search any supported platform:
- "Search LinkedIn for posts about AI agents"
- "Find recent Reddit discussions about React Server Components"
- "Search Twitter for posts about the latest OpenAI release"
Cursor will call the appropriate tool and return the results.
## Available Tools
All API Direct endpoints are available as MCP tools. This includes search across LinkedIn, Twitter/X, Facebook, Reddit, YouTube, Instagram, TikTok, forums, and news — as well as platform-specific tools for Twitter user profiles, Facebook pages/groups, and more. See the [endpoint documentation](/docs/linkedin-posts) for the full list.
## Troubleshooting
**"No API key provided"** — Make sure the `?token=` parameter is included in the URL.
**"Invalid API key"** — Double-check your API key in the [dashboard](https://apidirect.io/dashboard/keys). Keys start with `ak_live_`.
**Tools not appearing** — Make sure `.cursor/mcp.json` is valid JSON. Restart Cursor if needed.
**Global config** — To enable API Direct across all projects, add the config to Cursor's global MCP settings instead of a project-level file.
---
# OpenClaw
Use API Direct as an MCP server in OpenClaw to search social media and news from your AI agent.
## Setup
Add API Direct as an MCP server using the OpenClaw CLI:
```bash
openclaw mcp set apidirect '{"url":"https://apidirect.io/mcp?token=YOUR_API_KEY"}'
```
Replace `YOUR_API_KEY` with your key from the [API Keys](https://apidirect.io/dashboard/keys) page.
Verify the server was added:
```bash
openclaw mcp list
```
You can also view the server details with:
```bash
openclaw mcp show apidirect
```
## Usage
Once connected, ask your OpenClaw agent to search any supported platform:
- "Search LinkedIn for posts about AI agents"
- "Find recent Reddit discussions about React Server Components"
- "Search Twitter for posts about the latest OpenAI release"
OpenClaw will discover and call the appropriate API Direct tool automatically.
## Available Tools
All API Direct endpoints are available as MCP tools. This includes search across LinkedIn, Twitter/X, Facebook, Reddit, YouTube, Instagram, TikTok, forums, and news — as well as platform-specific tools for Twitter user profiles, Facebook pages/groups, and more. See the [endpoint documentation](/docs/linkedin-posts) for the full list.
## Troubleshooting
**"No API key provided"** — Make sure the `?token=` parameter is included in the URL.
**"Invalid API key"** — Double-check your API key in the [dashboard](https://apidirect.io/dashboard/keys). Keys start with `ak_live_`.
**Tools not appearing** — Run `openclaw mcp show apidirect` to verify the server config. Make sure the URL is correct.
**Removing the server** — To remove and re-add, run `openclaw mcp unset apidirect` and then set it again.
---
# Pricing
API Direct uses a pay-per-request pricing model. There are no monthly fees, subscriptions, or minimum commitments.
## Free Tier
Every account gets free requests per endpoint per month — **50 for most endpoints, 20 for Places Search, Place Reviews, and Place Photos**. No credit card required. Free requests reset on the 1st of each month.
## Endpoint Pricing
Prices range from **$0.002 to $0.01 per request** depending on the endpoint.
LinkedIn
| Endpoint | Price |
|----------|-------|
| Search Posts | $0.006/request |
| Person Posts | $0.006/request |
| Post Details | $0.002/request |
| Company Details | $0.006/request |
| Company Posts | $0.006/request |
| Search Companies | $0.006/request |
| Search Jobs | $0.006/request |
| Job Details | $0.002/request |
Twitter / X
| Endpoint | Price |
|----------|-------|
| Search Posts | $0.006/page |
| Search Users | $0.006/page |
| User Profile | $0.006/request |
| User Tweets | $0.006/page |
| User Followers | $0.006/page |
| User Following | $0.006/page |
| Verified Followers | $0.006/page |
| User Replies | $0.006/page |
| Tweet Details | $0.006/request |
| Tweet Retweets | $0.006/page |
| Tweet Quotes | $0.006/page |
| Tweet Comments | $0.006/page |
| Trends | $0.006/request |
Facebook
| Endpoint | Price |
|----------|-------|
| Page Details | $0.008/request |
| Page Posts | $0.008/page |
| Page Photos | $0.008/page |
| Page Videos | $0.008/page |
| Page Reels | $0.008/page |
| Page Reviews | $0.008/page |
| Group Details | $0.008/request |
| Group Posts | $0.008/page |
| Group Posts Search | $0.008/page |
| Post Comments | $0.008/page |
| Search Posts | $0.008/page |
| Search Pages | $0.008/page |
| Search Videos | $0.008/page |
| Search Events | $0.008/page |
| Search Locations | $0.004/request |
Instagram
| Endpoint | Price |
|----------|-------|
| Search Posts | $0.006/page |
| Search Users | $0.006/request |
| User Profile | $0.006/request |
| User Posts | $0.006/page |
| Post Details | $0.006/request |
Threads
| Endpoint | Price |
|----------|-------|
| Search Posts | $0.006/request |
| Search Users | $0.006/request |
| User Profile | $0.006/request |
| User Posts | $0.006/request |
Truth Social
| Endpoint | Price |
|----------|-------|
| User Posts | $0.006/page |
TikTok
| Endpoint | Price |
|----------|-------|
| Search Videos | $0.006/page |
| Search Users | $0.006/page |
| User Profile | $0.006/request |
| Video Details | $0.006/request |
Reddit
| Endpoint | Price |
|----------|-------|
| Search Posts | $0.003/request |
| Search Comments | $0.003/page |
| Search Users | $0.003/request |
YouTube
| Endpoint | Price |
|----------|-------|
| Search Videos | $0.005/page |
| Search Channels | $0.005/page |
| Channel Details | $0.005/request |
| Video Details | $0.005/request |
| Video Comments | $0.005/page |
Google
| Endpoint | Price |
|----------|-------|
| Web Search | $0.004/page |
| AI Mode | $0.005/request |
| News Articles | $0.008/request |
| Forum Posts | $0.008/request |
Google Places
| Endpoint | Price |
|----------|-------|
| Places Search | $0.01/page |
| Place Details | $0.003/request |
| Place Reviews | $0.01/page |
| Place Photos | $0.01/page |
## How Billing Works
- You are only charged for **successful requests** (2xx responses)
- Failed requests (4xx, 5xx) are not billed
- For multi-page endpoints (most Twitter and Facebook endpoints, Reddit Comments, YouTube, Instagram Posts, Instagram User Posts, Truth Social User Posts, TikTok Search Videos, TikTok Search Users, Web Search, Places Search, Place Reviews, Place Photos), you are billed per page requested
- [Batch requests](/docs/batch) are free — each item inside a batch bills under its own endpoint at the rates above, exactly as a direct call (skipped or failed items are not billed)
- Charges accumulate and are billed when your balance reaches a threshold
## Add-ons
### Emotion Analysis
Add `get_sentiment=true` to any endpoint that returns posts, videos, comments, or reviews to include AI-powered emotion analysis using Plutchik's Wheel of Emotions. Each result receives scores (0-100) for 8 basic emotions (joy, trust, fear, surprise, sadness, disgust, anger, anticipation), a dominant emotion, emotional intensity (0-10), and overall polarity (`positive`, `negative`, or `neutral`).
**Cost:** +$0.001 per request on top of the base endpoint price. For multi-page endpoints, this applies per page.
## Adding a Payment Method
To use the API beyond the free tier, add a credit or debit card in your [billing dashboard](https://apidirect.io/dashboard/billing). You can also set [spending limits](/docs/spending-limits) to control your costs.
---
# Spending Limits
Spending limits let you cap your API costs on a daily and monthly basis. Configure them in your [dashboard settings](https://apidirect.io/dashboard/settings).
## Daily Limit
Set a maximum dollar amount you're willing to spend per day. Once your daily spend reaches this limit, all API requests will be blocked until the next day (UTC midnight).
## Monthly Limit
Set a maximum dollar amount you're willing to spend per calendar month. Once your monthly spend reaches this limit, all API requests will be blocked until the next month.
## What Happens When a Limit Is Exceeded
When you hit a spending limit, the API returns a `429` error:
```json
{
"error": "Daily spending limit reached",
"code": "daily_limit_exceeded",
"limit": 5.00,
"current": 4.98
}
```
Or for monthly limits:
```json
{
"error": "Monthly spending limit reached",
"code": "monthly_limit_exceeded",
"limit": 50.00,
"current": 49.97
}
```
Requests will resume automatically when the next period begins (next day for daily limits, next month for monthly limits).
## Setting Limits
1. Go to your [Dashboard Settings](https://apidirect.io/dashboard/settings)
2. Find the Spending Limits section
3. Enter your desired daily and/or monthly limit
4. Save your changes
## Tips
- Start with conservative limits while you're testing and increase them as needed
- Use daily limits to protect against runaway scripts or unexpected spikes
- Use monthly limits to set a hard budget cap
- You can change or remove limits at any time from the dashboard
---
# API Keys
API keys are used to authenticate your requests. Manage them from the [API Keys](https://apidirect.io/dashboard/keys) page in your dashboard.
## Creating a Key
1. Go to [Dashboard > API Keys](https://apidirect.io/dashboard/keys)
2. Click "Create API Key"
3. Copy your new key immediately — the full key is only shown once
Your key will look like:
```
ak_live_7f3a9b2c1d4e5f6a8b9c0d1e2f3a4b5c
```
## Key Limits
Each account can have up to **10 API keys**. All keys share the same account balance, usage limits, and spending limits.
## Revoking a Key
Revoking a key disables it immediately. Revoked keys can be re-enabled later from the dashboard. Use this to temporarily disable a key without deleting it.
## Deleting a Key
Deleting a key permanently removes it. This cannot be undone. Any application using the deleted key will start receiving `401` errors.
## Best Practices
**Use separate keys for different applications** - This makes it easy to revoke access for a specific app without affecting others.
**Never commit keys to source control** - Store your API key in environment variables or a secrets manager. Don't hard-code it in your application.
**Rotate keys periodically** - Create a new key, update your application, then delete the old key.
**Revoke unused keys** - If a key is no longer in use, revoke or delete it to reduce your attack surface.
## Using Your Key
Pass your API key in the `X-API-Key` header:
```bash
curl "https://apidirect.io/v1/reddit/posts?query=test" \
-H "X-API-Key: ak_live_7f3a9b2c1d4e5f6a8b9c0d1e2f3a4b5c"
```
```python
import requests
response = requests.get(
"https://apidirect.io/v1/reddit/posts",
headers={"X-API-Key": "ak_live_7f3a9b2c1d4e5f6a8b9c0d1e2f3a4b5c"},
params={"query": "test"}
)
```
---