> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads API

> Threads를 검색하고 공개 프로필, 게시물, 답글을 JSON으로 읽습니다. 좋아요, 답글, 리포스트, 인용, 공유 수와 게시 시각을 함께 받습니다.

공개 Threads 데이터를 비동기 task API로 JSON으로 읽습니다. `taskType` `SOCIAL`에 `platform` `threads`를 보내고 `action`으로 읽을 대상을 고릅니다. 완료된 요청당 **0.5크레딧**입니다.

## 요청

```bash theme={"theme":"css-variables"}
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": "threads", "action": "search", "query": "running shoes", "limit": 20 } }'
```

task를 제출한 뒤 `GET /v1/async/task/{id}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](https://docs.querying.ai/ko/concepts/async-tasks.md).

## 동작

| `action` | 읽는 대상 | 필수 |
| - | - | - |
| `search` (기본값) | 키워드의 게시물 | `query` |
| `profile` | 공개 프로필과 최근 게시물 | `username` |
| `post` | 게시물 하나 | `postUrl` |
| `replies` | 게시물의 답글 | `postUrl` |

`username`은 사용자 이름이나 프로필 URL을 받습니다. `postUrl`은 `https://www.threads.com/@natgeo/post/Dfzi22JJSYp` 같은 게시물 URL을 받습니다.

## 입력

* `query`: `search`에 필수입니다.
* `limit`: 선택. `search`와 `profile`은 1-50이며 기본값은 10입니다. `replies`는 1-500이며 기본값은 50입니다.

## 응답 예시

```json theme={"theme":"css-variables"}
{
  "platform": "threads",
  "action": "search",
  "query": "running shoes",
  "returnedCount": 1,
  "posts": [
    {
      "id": "4032816753373504516",
      "code": "Df3cXhtEmQE",
      "url": "https://www.threads.com/@bongdgzmn/post/Df3cXhtEmQE",
      "text": "Gave in to the hype as I am also looking for a new pair of daily running shoes.",
      "author": "bongdgzmn",
      "authorVerified": false,
      "publishedAt": "2026-11-18T02:34:01.000Z",
      "mediaType": "carousel",
      "likeCount": 62,
      "replyCount": 42,
      "repostCount": 1,
      "quoteCount": 0,
      "shareCount": 19,
      "isReply": false
    }
  ]
}
```

## 결과 필드

* 모든 응답은 `platform`과 `action`을 그대로 돌려줍니다. 목록에는 `returnedCount`가 있습니다.
* 게시물에는 `id`, `code`, `url`, `text`, `author`, `authorVerified`, `publishedAt`, `mediaType`(`text`, `image`, `video`, `carousel`), `images`, `videoUrl`, `likeCount`, `replyCount`, `repostCount`, `quoteCount`, `shareCount`, `isReply`가 있습니다. 답글에는 답한 상대의 사용자 이름인 `replyTo`가 더해집니다.
* `search`는 Threads가 보여 주는 순서대로 `posts`를 최대 50개 정도 돌려줍니다.
* `profile`은 `id`, `username`, `displayName`, `biography`, `bioLinks`, `avatarUrl`, `profileUrl`, `isVerified`, `isPrivate`, `followerCount`, `threadCount`, `recentPosts`를 돌려줍니다. `recentPosts`는 프로필 페이지에 보이는 최근 게시물 4-13개입니다.
* `post`는 `post`를 돌려줍니다. `replies`는 `replies`를 돌려주며 게시물당 10개 정도입니다. `availableCount`는 게시물의 답글 수이고, `partial: true`는 작성자가 답글을 숨긴 경우처럼 목록이 그 수보다 짧다는 뜻입니다.
* 없거나 공개되지 않은 프로필이나 게시물은 task를 `PAGE_UNAVAILABLE`로 끝냅니다. 완료된 요청만 과금합니다.

## 관련 문서

* [Instagram](https://docs.querying.ai/ko/engines/instagram.md)
* [YouTube](https://docs.querying.ai/ko/engines/youtube.md)
* [엔진 목록](https://docs.querying.ai/ko/engines/overview.md)
* [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.