> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/documentation/plans-and-usage/credits.md). # Credits Unified data API across Apartments.com, Apple App Store, Google Play, DuckDuckGo, Google Maps, Google News, Google Search, Reddit, Instagram, TikTok, Twitter, Yelp, and YouTube. **Base URL:** `https://api.pullbay.com` ## Authentication All requests require a Bearer token in the `Authorization` header: ```http Authorization: Bearer ``` ## Credit System Every request consumes credits in two parts: * **Base cost** — charged per request regardless of results * **Item cost** — charged per item returned (1 credit/item) **Formula:** `total = base_cost + (item_count × item_cost)` **Example:** `GET /apartments/properties` with 1 result returned → `100 + 1 = 101 credits` ### Credit Costs by Service | Service | Endpoint | Base | Per Item | | ----------------- | -------------------- | ---- | -------- | | **Apartments** | Search properties | 100 | 1 | | | Get property detail | 50 | 1 | | | Get property images | 2 | 1 | | | Get property reviews | 2 | 1 | | **App Store** | Get app | 1 | 1 | | | Search apps | 1 | 1 | | | Similar apps | 1 | 1 | | | Get reviews | 1 | 1 | | | Developer apps | 1 | 1 | | **DuckDuckGo** | Web search | 3 | 1 | | | Image search | 3 | 1 | | | News search | 3 | 1 | | | Video search | 3 | 1 | | **Google Maps** | Place search | 500 | 1 | | | Get place by FID | 500 | 1 | | | Place reviews | 160 | 1 | | **Google News** | By category | 4 | 1 | | | Search | 4 | 1 | | **Google Play** | Get app | 1 | 1 | | | Search apps | 1 | 1 | | | Similar apps | 1 | 1 | | | Reviews | 1 | 1 | | | Permissions | 1 | 1 | | | Data safety | 1 | 1 | | **Google Search** | Web search | 20 | 1 | | **Reddit** | Search posts | 50 | 1 | | | Get post | 10 | 1 | | | Post comments | 30 | 1 | | | Comment replies | 30 | 1 | | | Get user | 10 | 1 | | | User posts | 30 | 1 | | | User comments | 30 | 1 | | | Get subreddit | 30 | 1 | | | Subreddit posts | 30 | 1 | | **Instagram** | Resolve user ID | 50 | 1 | | | Get user by handle | 100 | 1 | | | Get user by ID | 100 | 1 | | | User posts | 50 | 1 | | | Tagged posts | 150 | 1 | | | User reels | 50 | 1 | | | User stories | 50 | 1 | | | Get post by code | 50 | 1 | | | Post comments | 75 | 1 | | **TikTok** | Get user | 50 | 1 | | | User posts | 60 | 1 | | | Get post by ID | 60 | 1 | | | Post comments | 30 | 1 | | | Comment replies | 30 | 1 | | | Search posts | 60 | 1 | | | Get post by URL | 30 | 1 | | | Get hashtag | 60 | 1 | | **Twitter** | Search | 160 | 1 | | | Get tweet | 4 | 1 | | | Get user by handle | 40 | 1 | | | Get user about | 2 | 1 | | | Get user by ID | 40 | 1 | | | User tweets | 160 | 1 | | **Yelp** | Get place by ID | 50 | 1 | | | Place reviews | 40 | 1 | | | Get place by handle | 50 | 1 | | | Search places | 50 | 1 | | **YouTube** | Get channel | 150 | 1 | | | Channel videos | 150 | 1 | | | Channel shorts | 150 | 1 | | | Channel live streams | 200 | 1 | | | Get video | 150 | 1 | | | Get short | 200 | 1 | | | Video comments | 10 | 1 | | | Search | 150 | 1 | | | Hashtag videos | 150 | 1 | | | Trending | 250 | 1 | ## Pagination Paginated endpoints support two mutually exclusive modes: * `page` — 1-indexed page number * `maxItems` — one-shot bulk pull up to the specified limit * `cursor` — opaque cursor string for cursor-paginated endpoints * `offset` — numeric string for offset-paginated endpoints (Google Maps) Pagination info is included in the response only when relevant fields are non-null: ```json { "pagination": { "page": 1, "hasNextPage": true, "cursor": "...", "offset": null } } ``` ## Response Envelope ### Success ```json { "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24", "status": 200, "message": "OK", "success": true, "data": [...], "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null }, "pricing": { "creditsCharged": 101 } } ``` `pagination` is omitted when all fields are null (non-paginated endpoints). ### Error ```json { "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24", "status": 400, "message": "Validation failed", "success": false, "error": { "code": "VALIDATION_ERROR" } } ``` **HTTP status codes:** * `400` — Bad request / validation error * `402` — Insufficient credits * `404` — Not found ## Apartments.com ### Search Properties `GET /apartments/properties` **Cost: 100 credits/request + 1 credit/item** Search Apartments.com properties by location with optional filters. Use `page` (1-indexed) or `maxItems` for bulk pull (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ---------------------------------------------------------- | | `location` | string (2–40) | Yes | e.g. `Seattle, WA` | | `sort` | enum | No | `default`, `lastUpdated`, `rentHighToLow`, `rentLowToHigh` | | `minRent` | number (0–999999999) | No | Minimum rent filter | | `maxRent` | number (0–999999999) | No | Maximum rent filter | | `minBed` | number (0–4) | No | Minimum bedroom count | | `maxBed` | number (0–4) | No | Maximum bedroom count | | `minBath` | number (0–3) | No | Minimum bathroom count | | `maxBath` | number (0–3) | No | Maximum bathroom count | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `page` | integer (1–100) | No | Page number | ### Get Property Detail `GET /apartments/properties/{propertyId}` **Cost: 50 credits/request + 1 credit/item** Returns full details for a property. Use the boolean flags to opt into extra fields. | Parameter | Type | Required | Description | | --------------------- | -------------------- | -------- | --------------------- | | `propertyId` | string (path) | Yes | e.g. `swv1xf7` | | `includeScore` | `"true"` / `"false"` | No | Include score data | | `includeModelDetails` | `"true"` / `"false"` | No | Include model details | | `includeImages` | `"true"` / `"false"` | No | Include images | ### Get Property Images `GET /apartments/properties/{propertyId}/images` **Cost: 2 credits/request + 1 credit/item** Returns photos, floor plans, virtual tours, and extended virtual tours. | Parameter | Type | Required | Description | | ------------ | ------------- | -------- | -------------- | | `propertyId` | string (path) | Yes | e.g. `swv1xf7` | ### Get Property Reviews `GET /apartments/properties/{propertyId}/reviews` **Cost: 2 credits/request + 1 credit/item** Returns reviews for a property. Use `page` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ------------ | --------------- | -------- | --------------- | | `propertyId` | string (path) | Yes | e.g. `7s2qyhy` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `page` | integer (1–100) | No | Page number | ## Apple App Store ### Get App `GET /appstore/apps` **Cost: 1 credit/request + 1 credit/item** Returns one application. Provide exactly one of `appId` or `bundleId`. | Parameter | Type | Required | Description | | ---------- | --------------------- | -------- | -------------------------- | | `appId` | string (`^\d{8,12}$`) | One of | e.g. `389801252` | | `bundleId` | string | One of | e.g. `com.burbn.instagram` | | `country` | string (2) | No | 2-letter country code | | `lang` | string | No | Language code e.g. `en` | ### Search Apps `GET /appstore/search` **Cost: 1 credit/request + 1 credit/item** Search the App Store for applications matching `term`. Use `page` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | ----------------------------- | | `term` | string (1–255) | Yes | Search term e.g. `ai dungeon` | | `country` | string (2) | No | 2-letter country code | | `lang` | string | No | Language code | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `page` | integer (1–5) | No | Page number | ### Get Similar Apps `GET /appstore/similar` **Cost: 1 credit/request + 1 credit/item** Returns applications similar to the supplied one. Provide exactly one of `appId` or `bundleId`. | Parameter | Type | Required | Description | | ---------- | ---------- | -------- | --------------------- | | `appId` | string | One of | e.g. `389801252` | | `bundleId` | string | One of | Bundle identifier | | `country` | string (2) | No | 2-letter country code | | `lang` | string | No | Language code | ### Get App Reviews `GET /appstore/reviews` **Cost: 1 credit/request + 1 credit/item** Returns reviews for one application. Use `page` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | --------------------- | | `appId` | string | One of | e.g. `389801252` | | `bundleId` | string | One of | Bundle identifier | | `country` | string (2) | No | 2-letter country code | | `sort` | enum | No | `recent`, `helpful` | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `page` | integer (1–10) | No | Page number | ### Get Developer Apps `GET /appstore/developer` **Cost: 1 credit/request + 1 credit/item** Returns all applications published by a single developer. | Parameter | Type | Required | Description | | ------------- | --------------------- | -------- | --------------------- | | `developerId` | string (`^\d{8,12}$`) | Yes | e.g. `389801255` | | `country` | string (2) | No | 2-letter country code | ## DuckDuckGo ### Web Search `GET /duckduckgo/search` **Cost: 3 credits/request + 1 credit/item** Returns web search results for `term`. | Parameter | Type | Required | Description | | ------------ | -------------- | -------- | --------------------------------------------------------- | | `term` | string (1–255) | Yes | Search query | | `region` | enum | Yes | e.g. `us-en`, `de-de` — full list in spec | | `safeSearch` | enum | Yes | `off`, `moderate`, `strict` | | `offset` | number (≥0) | No | Result offset for pagination | | `time` | enum | No | `a` (any), `d` (day), `w` (week), `m` (month), `y` (year) | ### Image Search `GET /duckduckgo/images` **Cost: 3 credits/request + 1 credit/item** Returns image search results for `term`. | Parameter | Type | Required | Description | | ------------ | -------------- | -------- | --------------------------- | | `term` | string (1–255) | Yes | Search query | | `region` | enum | Yes | Region code | | `safeSearch` | enum | Yes | `off`, `moderate`, `strict` | | `offset` | number (≥0) | No | Result offset | ### News Search `GET /duckduckgo/news` **Cost: 3 credits/request + 1 credit/item** Returns news articles for `term`. Use `time` to limit recency. | Parameter | Type | Required | Description | | ------------ | -------------- | -------- | --------------------------- | | `term` | string (1–255) | Yes | Search query | | `region` | enum | Yes | Region code | | `safeSearch` | enum | Yes | `off`, `moderate`, `strict` | | `offset` | number (≥0) | No | Result offset | | `time` | enum | No | `a`, `d`, `w`, `m`, `y` | ### Video Search `GET /duckduckgo/videos` **Cost: 3 credits/request + 1 credit/item** Returns video search results for `term`. | Parameter | Type | Required | Description | | ------------ | -------------- | -------- | --------------------------- | | `term` | string (1–255) | Yes | Search query | | `region` | enum | Yes | Region code | | `safeSearch` | enum | Yes | `off`, `moderate`, `strict` | | `offset` | number (≥0) | No | Result offset | | `time` | enum | No | `a`, `d`, `w`, `m`, `y` | ## Google Maps ### Search Places `GET /google-maps/place/search` **Cost: 500 credits/request + 1 credit/item** Search Google Maps for places by free-text query. Use `offset` (numeric string) or `maxItems` (mutually exclusive). Optional geo filters available. | Parameter | Type | Required | Description | | -------------- | ---------------- | -------- | ------------------------ | | `query` | string (1–200) | Yes | e.g. `pizza in New York` | | `countryCode` | string (2–5) | No | Country filter | | `languageCode` | string (2–10) | No | Language filter | | `latitude` | string | No | Latitude for geo filter | | `longitude` | string | No | Longitude for geo filter | | `zoom` | string | No | Map zoom level | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `offset` | string (`^\d+$`) | No | Numeric offset string | ### Get Place by FID `GET /google-maps/place/{fid}` **Cost: 500 credits/request + 1 credit/item** Returns full details for a place identified by its FID (e.g. `0x47e671d877937b0f:0xb975fcfa192f84d4`). | Parameter | Type | Required | Description | | -------------- | ------------- | -------- | ---------------------- | | `fid` | string (path) | Yes | Google Maps feature ID | | `countryCode` | string (2–5) | No | Country filter | | `languageCode` | string (2–10) | No | Language filter | ### Get Place Reviews `GET /google-maps/place/reviews` **Cost: 160 credits/request + 1 credit/item** Returns reviews for a place identified by its full Google Maps URL. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------------- | -------- | -------------------- | | `placeUrl` | string (URI, 10–1000) | Yes | Full Google Maps URL | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ## Google News ### Articles by Category `GET /google-news/category` **Cost: 4 credits/request + 1 credit/item** Returns top news articles for a given category. `languageCode` selects locale (e.g. `US:en`). | Parameter | Type | Required | Description | | -------------- | ---- | -------- | ------------------------------------------------------------------------------------------ | | `category` | enum | Yes | `business`, `entertainment`, `health`, `latest`, `science`, `sport`, `technology`, `world` | | `languageCode` | enum | No | e.g. `US:en`, `GB:en`, `DE:de` — full list in spec | ### Search Articles `GET /google-news/search` **Cost: 4 credits/request + 1 credit/item** Returns articles matching `query`. `resolveUrl=yes` follows Google's redirect to the publisher URL. | Parameter | Type | Required | Description | | -------------- | --------------- | -------- | --------------- | | `query` | string (1–500) | Yes | Search query | | `languageCode` | enum | No | Locale code | | `resolveUrl` | enum | No | `yes`, `no` | | `maxItems` | integer (1–100) | No | Bulk pull limit | ## Google Play ### Get App `GET /google-play/apps` **Cost: 1 credit/request + 1 credit/item** Returns full details for a single app by its package name. | Parameter | Type | Required | Description | | --------- | ---------- | -------- | ---------------------------- | | `appId` | string | Yes | e.g. `com.instagram.android` | | `country` | string (2) | No | 2-letter country code | | `lang` | string | No | Language code | ### Search Apps `GET /google-play/search` **Cost: 1 credit/request + 1 credit/item** Search the Google Play Store for apps. Returns lightweight summaries. | Parameter | Type | Required | Description | | --------- | -------------- | -------- | --------------------- | | `search` | string (1–255) | Yes | Search query | | `price` | enum | No | `all`, `free`, `paid` | | `country` | string (2) | No | 2-letter country code | | `lang` | string | No | Language code | ### Get Similar Apps `GET /google-play/similar` **Cost: 1 credit/request + 1 credit/item** Returns apps Google Play surfaces as similar to the supplied `appId`. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------- | | `appId` | string | Yes | e.g. `com.instagram.android` | ### Get App Reviews `GET /google-play/reviews` **Cost: 1 credit/request + 1 credit/item** Returns reviews for an app. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | --------------------------------- | | `appId` | string | Yes | Package name | | `country` | string (2) | No | 2-letter country code | | `lang` | string | No | Language code | | `sort` | enum | No | `NEWEST`, `RATING`, `HELPFULNESS` | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get App Permissions `GET /google-play/permissions` **Cost: 1 credit/request + 1 credit/item** Returns the list of Android permissions the app requests, grouped by category. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------- | | `appId` | string | Yes | e.g. `com.instagram.android` | ### Get Data Safety `GET /google-play/data-safety` **Cost: 1 credit/request + 1 credit/item** Returns the developer-declared Data Safety section: data shared, collected, security practices, and privacy policy URL. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------- | | `appId` | string | Yes | e.g. `com.instagram.android` | ## Google Search ### Web Search `GET /google-search/search` **Cost: 20 credits/request + 1 credit/item** Returns Google search results for `query`. Use `page` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | -------------------- | | `query` | string (1–1000) | Yes | Search query | | `safe` | string | No | Safe search setting | | `hl` | string | No | Language hint | | `country` | string | No | Country code | | `count` | `"10"` | No | Results per page | | `noEncode` | string | No | Disable URL encoding | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `page` | integer (≥1) | No | Page number | ## Reddit ### Search Posts `GET /reddit/search/post` **Cost: 50 credits/request + 1 credit/item** Search Reddit posts by keyword. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | -------------------------------------------- | | `keyword` | string (1–100) | Yes | e.g. `javascript` | | `sort` | enum | No | `relevance`, `hot`, `top`, `new`, `comments` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string (1–100) | No | Pagination cursor | ### Get Post `GET /reddit/post/{id}` **Cost: 10 credits/request + 1 credit/item** Returns a single Reddit post by its ID. | Parameter | Type | Required | Description | | --------- | ------------------- | -------- | -------------- | | `id` | string (path, 1–32) | Yes | e.g. `1qclvp3` | ### Get Post Comments `GET /reddit/post/{id}/comments` **Cost: 30 credits/request + 1 credit/item** Returns the top-level comment tree for a Reddit post. | Parameter | Type | Required | Description | | --------- | ------------------- | -------- | -------------------------------------------------- | | `id` | string (path, 1–32) | Yes | Post ID | | `sort` | enum | No | `best`, `top`, `new`, `controversial`, `old`, `qa` | ### Get Comment Replies `GET /reddit/post/{id}/comments/{commentId}/replies` **Cost: 30 credits/request + 1 credit/item** Returns replies to a specific comment on a Reddit post. | Parameter | Type | Required | Description | | ----------- | ------------------- | -------- | -------------------------------------------------- | | `id` | string (path, 1–32) | Yes | Post ID e.g. `1qclvp3` | | `commentId` | string (path, 1–32) | Yes | Comment ID e.g. `nzj5dke` | | `sort` | enum | No | `best`, `top`, `new`, `controversial`, `old`, `qa` | ### Get User `GET /reddit/user/{username}` **Cost: 10 credits/request + 1 credit/item** Returns a Reddit user profile by username (without `u/`). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------- | | `username` | string (path, 1–100) | Yes | e.g. `spez` | ### Get User Posts `GET /reddit/user/{username}/posts` **Cost: 30 credits/request + 1 credit/item** Returns posts submitted by a Reddit user. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ------------------- | | `username` | string (path, 1–100) | Yes | Reddit username | | `sort` | enum | No | `hot`, `top`, `new` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string (1–100) | No | Pagination cursor | ### Get User Comments `GET /reddit/user/{username}/comments` **Cost: 30 credits/request + 1 credit/item** Returns comments authored by a Reddit user. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ------------------- | | `username` | string (path, 1–100) | Yes | Reddit username | | `sort` | enum | No | `hot`, `top`, `new` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string (1–100) | No | Pagination cursor | ### Get Subreddit `GET /reddit/subreddit/{name}` **Cost: 30 credits/request + 1 credit/item** Returns a subreddit profile by its name (without `r/`). | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ------------------ | | `name` | string (path, 1–100) | Yes | e.g. `programming` | ### Get Subreddit Posts `GET /reddit/subreddit/{name}/posts` **Cost: 30 credits/request + 1 credit/item** Returns posts from a subreddit. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ------------------- | | `name` | string (path, 1–100) | Yes | Subreddit name | | `sort` | enum | No | `hot`, `top`, `new` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string (1–100) | No | Pagination cursor | ## Instagram ### Resolve User ID `GET /instagram/userid/{handle}` **Cost: 50 credits/request + 1 credit/item** Returns whether the handle is available and, if it exists, the resolved Instagram user ID. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ---------------- | | `handle` | string (path, 1–100) | Yes | e.g. `instagram` | ### Get User by Handle `GET /instagram/user/handle/{handle}` **Cost: 100 credits/request + 1 credit/item** Returns an Instagram user profile by handle (without `@`). | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ---------------- | | `handle` | string (path, 1–100) | Yes | e.g. `instagram` | ### Get User by ID `GET /instagram/user/{id}` **Cost: 100 credits/request + 1 credit/item** Returns an Instagram user profile by numeric user ID. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | --------------- | | `id` | string (path, 1–100) | Yes | e.g. `25025320` | ### Get User Posts `GET /instagram/user/{id}/posts` **Cost: 50 credits/request + 1 credit/item** Returns posts published by a user. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------- | | `id` | string (path, 1–100) | Yes | User ID | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Tagged Posts `GET /instagram/user/{id}/posts/tagged` **Cost: 150 credits/request + 1 credit/item** Returns posts where the user is tagged. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------- | | `id` | string (path, 1–100) | Yes | User ID | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get User Reels `GET /instagram/user/{id}/reels` **Cost: 50 credits/request + 1 credit/item** Returns reels published by a user. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------- | | `id` | string (path, 1–100) | Yes | User ID | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get User Stories `GET /instagram/user/{id}/stories` **Cost: 50 credits/request + 1 credit/item** Returns the user's currently-active Instagram stories (non-paginated). | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ----------------------- | | `id` | string (path, 1–100) | Yes | User ID e.g. `25025320` | ### Get Post by Shortcode `GET /instagram/post/code/{code}` **Cost: 50 credits/request + 1 credit/item** Returns a single post by its shortcode (the segment after `/p/` in the URL). | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ------------------ | | `code` | string (path, 1–100) | Yes | e.g. `CzABCdef123` | ### Get Post Comments `GET /instagram/post/{id}/comments` **Cost: 75 credits/request + 1 credit/item** Returns comments on an Instagram post. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | -------------------------- | | `id` | string (path, 1–100) | Yes | e.g. `3890548995286221889` | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ## TikTok ### Get User by Handle `GET /tiktok/user/handle/{username}` **Cost: 50 credits/request + 1 credit/item** Returns a TikTok user profile by handle (without `@`). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ------------- | | `username` | string (path, 1–100) | Yes | e.g. `tiktok` | ### Get User Posts `GET /tiktok/user/{id}/posts` **Cost: 60 credits/request + 1 credit/item** Returns posts published by a TikTok user. Use `cursor` or `maxItems` (mutually exclusive). `region` may bias results toward a specific country. | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ---------------------- | | `id` | string (path, 1–100) | Yes | e.g. `107955` | | `region` | string (2–5) | No | Country code e.g. `US` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Post by ID `GET /tiktok/post/{id}` **Cost: 60 credits/request + 1 credit/item** Returns a single TikTok post by its numeric ID. | Parameter | Type | Required | Description | | --------- | ------------------- | -------- | -------------------------- | | `id` | string (path, 1–50) | Yes | e.g. `7636131611674692894` | | `region` | string (2–5) | No | Country code | ### Get Post Comments `GET /tiktok/post/{id}/comments` **Cost: 30 credits/request + 1 credit/item** Returns comments on a TikTok post. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------- | | `id` | string (path, 1–100) | Yes | Post ID | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Comment Replies `GET /tiktok/post/{id}/comments/{commentId}/replies` **Cost: 30 credits/request + 1 credit/item** Returns replies to a specific TikTok comment. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ----------- | -------------------- | -------- | -------------------------- | | `id` | string (path, 1–100) | Yes | Post ID | | `commentId` | string (path, 1–100) | Yes | e.g. `7636187917325304607` | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Search Posts `GET /tiktok/post/search` **Cost: 60 credits/request + 1 credit/item** Search TikTok posts by keyword. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ----------- | --------------- | -------- | ----------------- | | `keyword` | string (1–100) | Yes | e.g. `recipe` | | `region` | string (2–5) | No | Country code | | `dateRange` | string | No | Date range filter | | `sortType` | string | No | Sort type | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Post by URL `GET /tiktok/post` **Cost: 30 credits/request + 1 credit/item** Returns a single TikTok post by its full URL. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | --------------------- | | `url` | string (URI, 1–2048) | Yes | Full TikTok video URL | ### Get Hashtag `GET /tiktok/hashtag/handle/{name}` **Cost: 60 credits/request + 1 credit/item** Returns a TikTok hashtag profile by name (without `#`). | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ----------- | | `name` | string (path, 1–100) | Yes | e.g. `fyp` | ## Twitter ### Search `GET /twitter/search` **Cost: 160 credits/request + 1 credit/item** Search tweets by query. Use `cursor` or `maxItems` (mutually exclusive). Default sort is `Latest`. | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ---------------------------------------- | | `query` | string (1–100) | Yes | Search query | | `sort` | enum | No | `Top`, `Latest` (default: `Latest`) | | `useFirst` | `"true"` / `"false"` | No | Use first result mode (default: `false`) | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Tweet `GET /twitter/tweet/{id}` **Cost: 4 credits/request + 1 credit/item** Returns a single tweet by its numeric ID. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ----------- | | `id` | string (path, 1–100) | Yes | e.g. `20` | ### Get User by Handle `GET /twitter/handle/{handle}` **Cost: 40 credits/request + 1 credit/item** Returns a Twitter user by handle (without `@`). | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | --------------- | | `handle` | string (path, 1–100) | Yes | e.g. `elonmusk` | ### Get User About `GET /twitter/handle/{handle}/about` **Cost: 2 credits/request + 1 credit/item** Returns extended about/bio details for a Twitter user by handle. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | --------------- | | `handle` | string (path, 1–100) | Yes | e.g. `elonmusk` | ### Get User by ID `GET /twitter/user/{id}` **Cost: 40 credits/request + 1 credit/item** Returns a Twitter user by their numeric user ID. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | --------------- | | `id` | string (path, 1–100) | Yes | e.g. `44196397` | ### Get User Tweets `GET /twitter/user/{id}/tweets` **Cost: 160 credits/request + 1 credit/item** Returns tweets posted by a user. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------------- | | `id` | string (path, 1–100) | Yes | User ID e.g. `44196397` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ## Yelp ### Get Place by ID `GET /yelp/place/{id}` **Cost: 50 credits/request + 1 credit/item** Returns a Yelp place by its Yelp business ID. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ----------------------------- | | `id` | string (path, 1–200) | Yes | e.g. `JQNDglh1GHuvHriHAcJ1yg` | ### Get Place Reviews `GET /yelp/place/{id}/reviews` **Cost: 40 credits/request + 1 credit/item** Returns reviews for a Yelp place. Use `page` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ---------------- | | `id` | string (path, 1–200) | Yes | Yelp business ID | | `sortBy` | string (1–50) | No | Sort option | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `page` | integer (1–100) | No | Page number | ### Get Place by Handle `GET /yelp/place/handle/{handle}` **Cost: 50 credits/request + 1 credit/item** Returns a Yelp place by its handle/slug. | Parameter | Type | Required | Description | | --------- | -------------------- | -------- | ---------------------------- | | `handle` | string (path, 1–200) | Yes | e.g. `starbucks-seattle-121` | ### Search Places `GET /yelp/search` **Cost: 50 credits/request + 1 credit/item** Search Yelp places by query and location. Use `page` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | ------------------ | | `query` | string (1–200) | Yes | e.g. `coffee` | | `location` | string (1–200) | Yes | e.g. `Seattle, WA` | | `sortBy` | string (1–50) | No | Sort option | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `page` | integer (1–100) | No | Page number | ## YouTube ### Get Channel `GET /youtube/channel` **Cost: 150 credits/request + 1 credit/item** Returns channel details. Provide exactly one of `id`, `handle`, or `channelUrl`. | Parameter | Type | Required | Description | | ------------ | --------------------- | -------- | ---------------- | | `id` | string (1–100) | One of | Channel ID | | `handle` | string (1–100) | One of | e.g. `@MrBeast` | | `channelUrl` | string (URI, 10–1000) | One of | Full channel URL | ### Get Channel Videos `GET /youtube/channel/{id}/videos` **Cost: 150 credits/request + 1 credit/item** Returns videos uploaded by the channel. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ------------------------------- | | `id` | string (path, 1–100) | Yes | e.g. `UCX6OQ3DkcsbYNE6H8uQQuVA` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Channel Shorts `GET /youtube/channel/{id}/shorts` **Cost: 150 credits/request + 1 credit/item** Returns shorts uploaded by the channel. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------- | | `id` | string (path, 1–100) | Yes | Channel ID | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Channel Live Streams `GET /youtube/channel/{id}/live-streams` **Cost: 200 credits/request + 1 credit/item** Returns live streams (current and past) for the channel. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ---------- | -------------------- | -------- | ----------------- | | `id` | string (path, 1–100) | Yes | Channel ID | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Video `GET /youtube/video` **Cost: 150 credits/request + 1 credit/item** Returns full metadata for a single video by its 11-character video ID. | Parameter | Type | Required | Description | | --------- | ------------- | -------- | ------------------ | | `id` | string (5–20) | Yes | e.g. `dQw4w9WgXcQ` | | `type` | enum | No | `shorts`, `video` | ### Get Short `GET /youtube/shorts/{id}` **Cost: 200 credits/request + 1 credit/item** Returns full metadata for a single short by its video ID. | Parameter | Type | Required | Description | | --------- | ------------------- | -------- | ------------------ | | `id` | string (path, 5–20) | Yes | e.g. `dQw4w9WgXcQ` | ### Get Video Comments `GET /youtube/comments` **Cost: 10 credits/request + 1 credit/item** Returns top-level comments for a video. Use `cursor` or `maxItems` (mutually exclusive). Default sort is `top`. | Parameter | Type | Required | Description | | ---------- | --------------- | -------- | --------------------------- | | `id` | string (5–20) | Yes | Video ID e.g. `dQw4w9WgXcQ` | | `sort` | enum | No | `top`, `latest` | | `maxItems` | integer (1–500) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Search YouTube `GET /youtube/search` **Cost: 150 credits/request + 1 credit/item** Search YouTube. `mode` selects what to search for. Use `cursor` or `maxItems` (mutually exclusive). | Parameter | Type | Required | Description | | ------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `query` | string (1–100) | Yes | Search query | | `mode` | enum | Yes | `video`, `channel`, `playlist` | | `sortBy` | enum | No | `relevance`, `rating`, `upload_date`, `view_count` | | `lang` | string (2–5) | No | Language code | | `geo` | string (2–5) | No | Country code | | `duration` | enum | No | `short`, `medium`, `long` | | `features` | enum | No | `360`, `hd`, `subtitles`, `creative_commons`, `3d`, `live`, `purchased`, `4k`, `location`, `hdr`, `vr180` | | `uploadDate` | enum | No | `hour`, `today`, `week`, `month`, `year` | | `maxItems` | integer (1–200) | No | Bulk pull limit | | `cursor` | string | No | Pagination cursor | ### Get Hashtag Videos `GET /youtube/hashtag` **Cost: 150 credits/request + 1 credit/item** Returns videos tagged with `tag` from a single request (non-paginated). | Parameter | Type | Required | Description | | --------- | -------------- | -------- | ------------ | | `tag` | string (1–100) | Yes | e.g. `music` | ### Get Trending Videos `GET /youtube/trending` **Cost: 250 credits/request + 1 credit/item** Returns currently trending videos. Use `geo` to target a country. | Parameter | Type | Required | Description | | --------- | ------------ | -------- | --------------- | | `geo` | string (2–5) | No | e.g. `US`, `GB` |