소셜 데이터 API | BeatAPI API Documentation

BeatAPI Social Data는 지원되는 소셜 플랫폼의 공개 데이터를 조회하는 개발자용 동기식 API입니다. BeatAPI API 키와 BeatAPI가 관리하는 액션 ID를 사용하며, 계정, 라우팅, 원본 응답 세부 정보는 API 뒤에 숨겨져 있습니다.

빠른 시작

Social Data 액션 카탈로그에서 액션을 고른 다음 액션 ID와 파라미터를 보내세요.

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"douyin.web.fetch_one_video","params":{"aweme_id":"7364837462110"}}'

공개 엔드포인트는 POST /v1/social-data/call입니다. 이 엔드포인트에서는 model 필드가 필요 없으며, 액션 ID로 작업이 정해집니다. 데이터 제공 측 고유의 URL이나 경로 이름을 보내지 마세요.

요청

필드	타입	필수	설명
`action`	string	예	카탈로그의 BeatAPI 액션 ID입니다.
`params`	object	아니요	선택한 카탈로그 항목에 설명된 파라미터입니다. 파라미터가 없는 액션이면 생략하세요.

action은 douyin.web.fetch_one_video처럼 카탈로그에 나온 식별자 형식을 따라야 합니다. 필수 필드, 타입, 허용 값은 카탈로그 항목의 input_schema를 기준으로 합니다. 카탈로그 메서드가 GET인 액션은 파라미터 값이 스칼라입니다. POST 액션의 params는 JSON 객체입니다.

요청 본문은 512 KiB로 제한됩니다. 인증에는 Authorization: Bearer <BeatAPI API key>를 사용합니다. 클라이언트가 같은 요청을 재시도할 수 있다면 Idempotency-Key를 보낼 수 있으며, 같은 키를 다른 요청에 재사용하면 거부됩니다.

응답

성공한 호출은 정규화된 BeatAPI 응답 형식을 반환합니다.

{
  "object": "social_data.call",
  "status": "succeeded",
  "request_id": "req_01H...",
  "action": "douyin.web.fetch_one_video",
  "data": {
    "aweme_id": "7364837462110"
  }
}

data는 선택한 액션에 대해 반환되는 공개 결과입니다. BeatAPI는 반환하기 전에 데이터 제공 측의 이름, 요청 ID, 캐시 URL, 라우팅 필드, 원본 오류 세부 정보를 제거합니다. 응답은 동기식이며, HTTP 응답이 성공하면 액션이 완료된 것입니다.

정적 액션 카탈로그는 액션별 출력 형식이 아니라 입력을 문서화합니다. 현재 output_schema와 준비 상태는 Capabilities Inspect로 확인하세요. runnable은 액션을 실행할 수 있지만 출력 형식이 공개되지 않았다는 뜻이므로, 고정된 구조를 가정하지 말고 실제 응답에서 필드를 읽으세요.

크리에이터 발굴

두 액션은 플랫폼 카탈로그로는 알 수 없는 것, 즉 어떤 크리에이터와 비슷한 사람이 누구인지, 그리고 어떻게 연락할 수 있는지 알려 줍니다. 다른 모든 액션과 같은 엔드포인트와 action / params 계약을 사용합니다.

`creator.discover`

시드 계정 하나를 주면 플랫폼이 직접 비슷하다고 판단한 크리에이터를 반환하며, 각 크리에이터에는 프로필에 공개된 연락처가 이미 추가되어 있습니다.

파라미터	타입	필수	설명
`platform`	string	예	`instagram`. 이 액션이 읽는 관련 계정 그래프는 Instagram의 것이며, 다른 플랫폼에는 시드에서 비슷한 계정을 찾는 단계가 없습니다.
`seed`	string	예	핸들 또는 프로필 URL(예: `gymshark` 또는 `https://www.instagram.com/gymshark/`).
`limit`	integer	아니요	반환할 비슷한 크리에이터 수, `1`–`6`. 기본값은 `6`입니다.

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"creator.discover","params":{"platform":"instagram","seed":"gymshark","limit":3}}'

시드 계정 자체도 비슷한 크리에이터와 함께 반환되며 discovered_via: "input"로 표시됩니다. 따라서 limit은 비슷한 크리에이터 수이고 응답에는 그보다 한 행이 더 들어 있습니다.

`creator.contacts`

이미 알고 있는 크리에이터를 주면 각각에 대해 같은 기록을 반환하며, 발굴 단계는 없습니다.

파라미터	타입	필수	설명
`platform`	string	예	`instagram`, `tiktok` 또는 `youtube`.
`handles`	string[]	예	핸들 또는 프로필 URL 1~8개.

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"creator.contacts","params":{"platform":"youtube","handles":["@mkbhd"]}}'

크리에이터 기록

두 액션 모두 data에 크리에이터마다 객체 하나씩, 같은 형식으로 반환합니다.

필드	설명
`platform`, `handle`, `name`, `profile_url`, `user_id`	신원 정보.
`followers`, `following`, `posts_count`, `engagement_rate_pct`, `avg_likes`	오디언스와 활동. 수치가 추정값이면 `followers_estimated`에 표시됩니다.
`email`, `extra_emails`, `email_status`, `email_source`	연락처. 공개된 연락처가 없으면 `email`은 `null`입니다(아래 참고).
`website`, `linkedin_url`, `instagram_url`, `tiktok_url`, `youtube_url`, `facebook_url`	프로필에서 찾은 링크.
`bio`, `category`, `country`, `verified`, `is_business`, `is_private`	프로필 속성.
`lead_score`, `lead_grade`, `lead_tier`	분류용으로 위 필드를 종합한 등급.
`discovered_via`	직접 지정한 크리에이터는 `input`, 발굴로 찾은 크리에이터는 `instagram_related`.

email_source는 주소를 어디서 찾았는지 알려 줍니다. 크리에이터가 링크한 웹사이트에서 찾은 주소는 본인이 아니라 홍보하는 브랜드의 것일 수 있으므로, 개인 연락처로 쓰기 전에 email_source를 확인하세요.

크레딧

다른 모든 액션과 달리 이 두 액션은 요청당이 아니라 반환된 크리에이터당 과금됩니다. GET /v1/social-data/pricing의 billing_unit에 이 내용이 표시됩니다. 이 두 액션은 "creator", 나머지는 "request".

아무도 찾지 못한 요청은 빈 data 배열을 가진 성공 응답이며, 그래도 크리에이터 한 명분의 크레딧이 소비됩니다. 찾았든 못 찾았든 발굴 작업은 수행되었기 때문입니다. 지출 상한은 limit과 handles의 크기로 정하세요.

오류와 크레딧

오류는 일반적인 BeatAPI 오류 형식을 사용하며, 모든 오류에 고정된 code와 retryable이 있습니다. 재시도 정책은 오류를 참고하세요.

HTTP 상태	코드	의미
400	`bad_request`	JSON, 액션 또는 파라미터가 잘못되었습니다. 메시지에 해당 필드가 표시됩니다.
401	`missing_api_key` / `invalid_api_key`	키를 보내지 않았거나 키가 잘못되었거나 만료·비활성화·소진되었습니다.
402	`insufficient_credits`	잔액 부족: 잔액이 0이거나 호출 가격보다 적습니다.
403	`forbidden`	키나 계정에 이 호출 권한이 없습니다.
404	`not_found`	요청한 액션이나 리소스를 찾을 수 없습니다.
409	`idempotency_conflict`	멱등성 키가 다른 요청에 재사용되었습니다.
429	`rate_limit_exceeded`	요청 한도에 도달했습니다. `Retry-After`초 기다리세요.
500	`internal_error`	예기치 않은 내부 오류입니다. 재시도할 수 있습니다.
503	`processing_unavailable` 또는 그 밖의 `processing_*` 코드	요청을 완료할 수 없습니다. 백오프를 두고 재시도하세요.

실패한 호출은 크레딧을 소비하지 않습니다. 성공한 호출은 계정의 현재 BeatAPI 가격과 선택한 액션에 따라 크레딧을 소비합니다. 내부 원가와 내부 URL은 이 문서나 공개 응답에 절대 포함되지 않습니다.

MCP

같은 카탈로그와 계약을 capabilities_search, capabilities_inspect, capabilities_run MCP 도구와 Capabilities API로도 사용할 수 있습니다. 플랫폼과 액션을 사용자의 말 그대로(小红书搜索笔记, tiktok user profile) 검색하세요. 플랫폼 이름만 검색하면 기능별로 묶은 개요가 반환됩니다. Search가 반환한 data:<action-id> 레퍼런스를 그대로 사용하고, 각 응답의 next를 따르세요.

MCP는 기본적으로 큰 결과의 미리보기를 반환합니다. 1시간 안에 전체 결과를 무료로 받으려면 같은 API 키와 원래 reference를 사용하고, operation을 "result"로 설정한 뒤 반환된 request_id를 포함하세요. 별도의 외부 자격 증명이나 고유 경로는 필요 없습니다.

Social Data API