---
name: read-social-data
description: "Search YouTube, Instagram or Threads, or read a public video, channel, profile or post with its comments or replies, or a YouTube transcript, as JSON with views, likes, comment counts and publish times. Use it to see how a brand, product or topic shows up on social platforms next to AI answers. 0.5 credits per completed read."
---

# Read YouTube, Instagram and Threads with querying.ai

Send `Authorization: Bearer $QUERYING_API_KEY` on every request to https://api.querying.ai. Getting a key, and the 500 credits a new account starts with: https://querying.ai/auth.md

Send `taskType` `SOCIAL`. `payload.platform` picks the site and `payload.action` what to read; each action needs one identifier.

| `platform` | `action` | Needs | Returns |
| --- | --- | --- | --- |
| `youtube` | `search` (default), `recent` | `query` | `videos[]` with views, likes, duration, channel and publish time |
| `youtube` | `video` | `videoId` | The watch page: description, tags, chapters, counts and related videos |
| `youtube` | `comments` | `videoId` | `comments[]` and their replies with likes and publish times |
| `youtube` | `channel`, `channel_videos` | `channel` | The channel's details, or its videos, Shorts or live streams |
| `youtube` | `transcript` | `videoId` | Caption `text` and timed `segments` |
| `instagram` | `search` (default) | `query` | `posts[]`: posts and reels for a keyword |
| `instagram` | `profile`, `posts` | `username` | The profile and its 12 most recent posts; `posts` adds each post's likes, comments and publish time |
| `instagram` | `post`, `comments` | `postUrl` | One post or reel with its first comments, or its comments |
| `threads` | `search` (default) | `query` | `posts[]` with likes, replies, reposts, quotes and shares |
| `threads` | `profile` | `username` | The profile and its recent posts |
| `threads` | `post`, `replies` | `postUrl` | One post, or its replies |

## Submit

```bash
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskType": "SOCIAL", "payload": {"platform": "youtube", "action": "search", "query": "wireless earbuds review", "limit": 10}}'
```

- `username` takes a username or a profile URL, `videoId` a video ID or URL, and `channel` a channel ID, an @handle or a channel URL.
- `limit` sets how many items a list returns. YouTube `search` also takes `order`, `publishedAfter`, `type`, `videoDuration`, `features` and `pageToken` (the `nextPageToken` of the previous page).

## Read the result

Tasks run asynchronously. The POST returns `task.id` with `status` `QUEUED`. Poll `GET /v1/async/task/{id}` every few seconds until `task.status` is `COMPLETED` or `FAILED`, or add `"webhook": {"url": "https://your.server/hook"}` to the request and the finished task arrives at that URL as a POST. A finished task stays readable for 24 hours.

- Every response echoes `platform` and `action`; lists carry `returnedCount`.
- A video, account or post that does not exist or is not public fails with `PAGE_UNAVAILABLE`. Failed tasks are not charged.

## Errors

| HTTP | `code` | When |
| --- | --- | --- |
| 401 | `MISSING_API_KEY` | The key is missing, wrong, expired or revoked. |
| 402 | `INSUFFICIENT_CREDITS` | The account balance is below the task's credits. |
| 403 | `KEY_SCOPE_DENIED` | The key is limited to other engines. |
| 422 | `REGION_UNSUPPORTED` | The engine serves other countries; pick another engine or country. |
| 429 | `KEY_DAILY_CREDIT_LIMIT` | The key reached its daily credit limit; `details.retryAfterSec` counts down to the next UTC day. |

## Over MCP

`read_social` on https://mcp.querying.ai/mcp submits and waits for the result.

Reference: https://docs.querying.ai/engines/youtube, https://docs.querying.ai/engines/instagram and https://docs.querying.ai/engines/threads
