SNSTrackerSNSTracker

API Reference

개요

SNSTracker API를 사용하면 모니터링 피드와 채널을 프로그래밍 방식으로 관리할 수 있습니다. 피드(동영상, 게시물 등)와 채널(계정, 프로필)을 생성하고, 최신 데이터를 얻기 위해 새로고침하며, 웹훅을 통해 실시간 알림을 받을 수 있습니다.

인증

모든 API 요청에는 API 키를 사용하는 인증이 필요합니다. X-API-Key 헤더에 API 키를 포함하세요.

API 키 발급 방법:

  1. SNSTracker에 로그인
  2. 설정 → API 키로 이동
  3. 새 API 키를 생성하거나 기존 키 사용
  4. API 키 복사(생성 시 한 번만 표시됨)

API 엔드포인트

1. 피드 생성

피드 URL(동영상, 게시물 등)을 제출하여 모니터링 피드를 생성합니다.

POST /api/v1/feeds

요청

헤더:

  • X-API-Key: API 키(필수)
  • Content-Type: application/json

요청 본문:

{
  "urls": [
    "https://www.tiktok.com/@user/video/1234567890",
    "https://www.instagram.com/p/ABC123/"
  ],
  "collectionId": "coll_abc123xyz"
}

파라미터:

  • urls (필수): 모니터링할 피드 URL 배열. 요청당 최대 200개 URL.
  • collectionId (선택): 피드가 추가될 컬렉션 ID. 제공되지 않으면 팀의 기본 컬렉션이 사용됩니다.

응답

성공 응답 (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "index": 0,
        "url": "https://www.tiktok.com/@user/video/1234567890",
        "platform": "tiktok",
        "feedId": "feed_abc123xyz",
        "success": true
      },
      {
        "index": 1,
        "url": "https://www.instagram.com/p/ABC123/",
        "platform": "instagram",
        "feedId": "feed_def456uvw",
        "success": true
      }
    ],
    "errors": [],
    "message": "피드가 성공적으로 생성되었습니다. 데이터는 곧 업데이트됩니다."
  }
}

응답 필드:

  • success: 성공적으로 생성된 피드 수
  • failed: 생성 실패한 피드 수
  • total: 제공된 URL의 총 개수
  • results: 각 URL에 대한 결과 배열
    • index: 요청 배열의 0부터 시작하는 인덱스
    • url: 검증 및 표준화된 URL
    • platform: 감지된 플랫폼(tiktok, instagram, youtube 등)
    • feedId: 생성된 피드의 고유 식별자
    • success: 피드 생성 성공 여부
    • skipped: (선택) 이미 존재하여 건너뛰었는지 여부
    • resumed: (선택) 중지된 피드가 재개되었는지 여부
    • error: (선택) 생성 실패 시 오류 메시지
  • errors: 실패한 URL의 오류 배열

요청 예시

curl -X POST https://snstracker.com/api/v1/feeds \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@user/video/1234567890"
    ]
  }'

2. 피드 새로고침

기존 피드를 즉시 새로고침하여 최신 데이터를 가져옵니다. 상태가 "Pending" 또는 "Tracked"인 피드만 새로고침할 수 있습니다.

POST /api/v1/feeds/refresh

요청

헤더:

  • X-API-Key: API 키(필수)
  • Content-Type: application/json

요청 본문:

{
  "feedIds": ["feed_abc123xyz", "feed_def456uvw"]
}

파라미터:

  • feedIds (필수): 새로고침할 피드 ID 배열

응답

성공 응답 (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "feedIds": ["feed_abc123xyz", "feed_def456uvw"],
    "total": 2,
    "message": "2개 피드를 성공적으로 새로고침했습니다"
  }
}

응답 필드:

  • success: 새로고침 작업 성공 여부
  • feedIds: 새로고침된 피드 ID 배열
  • total: 새로고침된 피드 수
  • message: 성공 메시지

요청 예시

curl -X POST https://snstracker.com/api/v1/feeds/refresh \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedIds": ["feed_abc123xyz"]
  }'

3. 채널 생성

채널 URL(계정 프로필 등)을 제출하여 모니터링 채널을 생성합니다.

Channel pricing note: Xiaohongshu channel tasks are priced separately from the default channel task price and currently cost 10 credits per successful request.

POST /api/v1/channels

요청

헤더:

  • X-API-Key: API 키(필수)
  • Content-Type: application/json

요청 본문:

{
  "urls": [
    "https://www.tiktok.com/@username",
    "https://www.instagram.com/username/"
  ],
  "collectionId": "coll_abc123xyz"
}

파라미터:

  • urls (필수): 모니터링할 채널 URL 배열. 요청당 최대 5개 URL.
  • collectionId (선택): 채널이 추가될 컬렉션 ID. 제공되지 않으면 팀의 기본 컬렉션이 사용됩니다.

응답

성공 응답 (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "index": 0,
        "url": "https://www.tiktok.com/@username",
        "platform": "tiktok",
        "channelId": "channel_abc123xyz",
        "success": true
      },
      {
        "index": 1,
        "url": "https://www.instagram.com/username/",
        "platform": "instagram",
        "channelId": "channel_def456uvw",
        "success": true
      }
    ],
    "errors": [],
    "message": "채널이 성공적으로 생성되었습니다. 데이터는 곧 업데이트됩니다."
  }
}

응답 필드:

  • success: 성공적으로 생성된 채널 수
  • failed: 생성 실패한 채널 수
  • total: 제공된 URL의 총 개수
  • results: 각 URL에 대한 결과 배열
    • index: 요청 배열의 0부터 시작하는 인덱스
    • url: 검증 및 표준화된 URL
    • platform: 감지된 플랫폼(tiktok, instagram, youtube 등)
    • channelId: 생성된 채널의 고유 식별자
    • success: 채널 생성 성공 여부
    • skipped: (선택) 이미 존재하여 건너뛰었는지 여부
    • resumed: (선택) 중지된 채널이 재개되었는지 여부
    • error: (선택) 생성 실패 시 오류 메시지
  • errors: 실패한 URL의 오류 배열

요청 예시

curl -X POST https://snstracker.com/api/v1/channels \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@username"
    ]
  }'

4. 채널 새로고침

기존 채널을 즉시 새로고침하여 최신 데이터를 가져옵니다. 상태가 "Pending" 또는 "Tracked"인 채널만 새로고침할 수 있습니다.

Channel pricing note: Xiaohongshu channel tasks are priced separately from the default channel task price and currently cost 10 credits per successful request.

POST /api/v1/channels/refresh

요청

헤더:

  • X-API-Key: API 키(필수)
  • Content-Type: application/json

요청 본문:

{
  "channelIds": ["channel_abc123xyz", "channel_def456uvw"]
}

파라미터:

  • channelIds (필수): 새로고침할 채널 ID 배열

응답

성공 응답 (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "channelIds": ["channel_abc123xyz", "channel_def456uvw"],
    "total": 2,
    "message": "2개 채널을 성공적으로 새로고침했습니다"
  }
}

응답 필드:

  • success: 새로고침 작업 성공 여부
  • channelIds: 새로고침된 채널 ID 배열
  • total: 새로고침된 채널 수
  • message: 성공 메시지

요청 예시

curl -X POST https://snstracker.com/api/v1/channels/refresh \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "channelIds": ["channel_abc123xyz"]
  }'

5. 피드 동기화

scrapy 서비스에서 피드 데이터를 직접 동기화합니다. 이 엔드포인트는 최신 피드 데이터를 즉시 가져오며, 동기화 성공 시 크레딧이 소모됩니다. 같은 팀의 모든 구성원, API 키, 모든 동기화 엔드포인트는 하나의 동시 실행 한도를 공유합니다. 공유 한도는 스타터 또는 유효한 구독이 없으면 1개, 스탠다드는 5개, 프리미엄은 10개입니다.

⚠️ 중요 안내: 이 동기화 엔드포인트는 독립형이며 웹 플랫폼과 연동되지 않습니다. 동기화 작업은 다음과 같습니다:

  • 웹 대시보드에서 피드 레코드를 생성하거나 업데이트하지 않습니다
  • 피드 목록이나 컬렉션에 표시되지 않습니다
  • 웹훅이나 알림을 트리거하지 않습니다
  • 오직 API 응답에서 직접 가져온 데이터를 반환합니다

이 엔드포인트는 API를 통한 일회성 데이터 조회용입니다. 웹 플랫폼에 표시되는 지속적인 모니터링 피드를 만들려면 피드 생성 엔드포인트를 사용하세요.

POST /api/v1/feeds/sync

요청

헤더:

  • X-API-Key: API 키(필수)
  • Content-Type: application/json

요청 본문:

{
  "url": "https://www.tiktok.com/@user/video/1234567890"
}

파라미터:

  • url (필수): 동기화할 피드 URL. 유효한 비어있지 않은 문자열이어야 합니다.

응답

성공 응답 (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.tiktok.com/@user/video/1234567890",
    "feedInfo": {
      "feed_id": "1234567890",
      "platform": 1,
      "platform_name": "tiktok",
      "url": "https://www.tiktok.com/@user/video/1234567890",
      "views": 1000000,
      "likes": 200000,
      "comments": 1000,
      "shares": 2000,
      "bookmarks": 200,
      "engagement": 512000,
      "description": "동영상 설명",
      "hashtags": ["tag1", "tag2"],
      "publish_at": 1234567890
    }
  }
}

응답 필드:

  • success: 동기화 작업 성공 여부
  • url: 동기화된 피드 URL
  • feedInfo: 지표, 설명, 해시태그 등을 포함한 전체 피드 정보

오류 응답:

  • 429 Too Many Requests: 팀의 동시 실행 한도에 도달했습니다. 요청은 대기열에 추가되지 않습니다.
  • 400 Bad Request: 크레딧 부족 또는 잘못된 URL

요청 예시

curl -X POST https://snstracker.com/api/v1/feeds/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@user/video/1234567890"
  }'

6. 채널 동기화

scrapy 서비스에서 채널 데이터를 직접 동기화합니다. 이 엔드포인트는 최신 채널 데이터를 즉시 가져오며, 동기화 성공 시 크레딧이 소모됩니다. 같은 팀의 모든 구성원, API 키, 모든 동기화 엔드포인트는 하나의 동시 실행 한도를 공유합니다. 공유 한도는 스타터 또는 유효한 구독이 없으면 1개, 스탠다드는 5개, 프리미엄은 10개입니다.

Channel pricing note: Xiaohongshu channel tasks are priced separately from the default channel task price and currently cost 10 credits per successful request.

⚠️ 중요 안내: 이 동기화 엔드포인트는 독립형이며 웹 플랫폼과 연동되지 않습니다. 동기화 작업은 다음과 같습니다:

  • 웹 대시보드에서 채널 레코드를 생성하거나 업데이트하지 않습니다
  • 채널 목록이나 컬렉션에 표시되지 않습니다
  • 웹훅이나 알림을 트리거하지 않습니다
  • 오직 API 응답에서 직접 가져온 데이터를 반환합니다

이 엔드포인트는 API를 통한 일회성 데이터 조회용입니다. 웹 플랫폼에 표시되는 지속적인 모니터링 채널을 만들려면 채널 생성 엔드포인트를 사용하세요.

POST /api/v1/channels/sync

요청

헤더:

  • X-API-Key: API 키(필수)
  • Content-Type: application/json

요청 본문:

{
  "url": "https://www.tiktok.com/@username"
}

파라미터:

  • url (필수): 동기화할 채널 URL. 유효한 비어있지 않은 문자열이어야 합니다.

응답

성공 응답 (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.tiktok.com/@username",
    "channelInfo": {
      "id": "1234567890",
      "platform": 1,
      "platform_name": "tiktok",
      "username": "username",
      "nickname": "User Name",
      "description": "채널 설명",
      "followers": 1000000,
      "followings": 2000,
      "likes": 200000000,
      "total_count": 1000,
      "track_count": 1000,
      "status": 1
    }
  }
}

응답 필드:

  • success: 동기화 작업 성공 여부
  • url: 동기화된 채널 URL
  • channelInfo: 지표, 설명 등을 포함한 전체 채널 정보

오류 응답:

  • 429 Too Many Requests: 팀의 동시 실행 한도에 도달했습니다. 요청은 대기열에 추가되지 않습니다.
  • 400 Bad Request: 크레딧 부족 또는 잘못된 URL

요청 예시

curl -X POST https://snstracker.com/api/v1/channels/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@username"
  }'

7. 채널 콘텐츠 동기화

채널 콘텐츠 한 페이지를 반환합니다. Instagram과 Reels는 요청당 최대 12개이며 자동으로 다음 페이지를 가져오지 않습니다. instagram은 이미지·동영상·캐러셀 게시물, reels는 Reels 동영상을 반환합니다.

POST /api/v1/channels/feeds/sync
X-API-Key: your-api-key
Content-Type: application/json

Request and pagination

{
  "platform": "instagram",
  "channel_name": "instagram"
}
  • count는 이 페이지에서 원하는 항목 수를 지정하는 선택적 양의 정수이며 기본값은 없습니다. 수량 제한은 플랫폼마다 다릅니다. Instagram과 Reels는 요청당 최대 12개를 반환하며, 실제 반환 수는 더 적을 수 있습니다. 생략하면 플랫폼의 기본 페이지 크기를 사용합니다.
  • 첫 페이지는 cursor를 생략합니다. 다음 페이지는 이전 next_cursor를 그대로 전달하고 platform, channel_name을 유지합니다. 마지막 페이지는 has_more=false, next_cursor=null입니다.
{
  "platform": "instagram",
  "channel_name": "instagram",
  "cursor": "previous-next-cursor"
}

성공적으로 조회한 페이지는 빈 페이지를 포함하여 페이지당 10 크레딧입니다. 실패한 요청만 무료이며 요청 전 최소 10 크레딧이 필요합니다. 다른 동기화 API와 팀 동시 실행 한도를 공유하고 대시보드 기록은 만들지 않습니다.

Response example (placeholder cursor) — reels, lunacut.edit, count=1

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "platform": "reels",
    "channel_name": "lunacut.edit",
    "channel_url": "https://www.instagram.com/lunacut.edit/",
    "requested_count": 1,
    "returned_count": 1,
    "has_more": true,
    "next_cursor": "cursor-from-response",
    "items": [
      {
        "feed_id": "4009169989985582972",
        "platform": 5,
        "platform_name": "reels",
        "type": "video",
        "url": "https://www.instagram.com/reel/Dejbt1JPz98/",
        "author_username": "lunacut.edit",
        "publish_at": 1792150387,
        "duration": 70.077,
        "view_count": 310475
      }
    ]
  }
}

platform and channel_name are required. channel_name is the username, not the display name; leading @ is accepted and dots are preserved. requested_count is null when count is omitted; returned_count equals items.length. Unknown metrics/timestamps are null. Posts may lack timestamps and carousel details. items uses the existing feed fields, including video_url, image_urls and cover_url; the example shows only selected fields. publish_at is Unix seconds and duration is seconds. Upstream order is preserved, without a most-popular sorting option; deduplicate across pages by feed_id. Empty pages can still have a next cursor; a carousel counts as one post.

items의 조회 수(view_count), 좋아요 수(like_count), 저장 수(bookmark_count), 댓글 수(comment_count) 등은 플랫폼과 채널 목록 API가 제공하는 데이터에 따라 달라집니다. 모든 지표를 얻을 수 있는 것은 아닙니다. 가져오지 못한 지표는 null로 반환되며, 0을 의미하지 않습니다.

채널 목록에 없는 지표를 추가로 조회하려면 해당 항목의 url을 요청 본문의 url로 지정하여 POST /api/v1/feeds/sync를 별도로 호출하세요. 상세 조회는 해당 API의 규칙에 따라 별도로 과금됩니다. 결과는 플랫폼이 실제로 제공하는 데이터에 따라 달라지므로 모든 누락 지표를 얻을 수 있다고 보장하지 않습니다.

HTTP: 400 invalid input/cursor or insufficient initial credits; 401 invalid API key; 403 disabled team or inaccessible channel; 402 insufficient credits at settlement; 429 team concurrency limit (Retry-After: 1); 502 upstream/invalid page; 503 service unavailable; 504 timeout.

8. 프로필 추가 정보 조회

POST /api/v1/channels/about/sync

Instagram과 Reels만 지원합니다. 입력은 /api/v1/channels/sync와 같은 필수 url입니다. Instagram: https://www.instagram.com/lunacut.edit/, Reels: https://www.instagram.com/lunacut.edit/reels/. platform, count, cursor는 필요하지 않습니다. 게시물 URL과 다른 플랫폼은 지원하지 않습니다.

curl -X POST https://snstracker.com/api/v1/channels/about/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/lunacut.edit/"}'

성공 요청당 80 크레딧이 차감되며 추가 필드가 null이어도 과금됩니다. 오류는 과금하지 않으며 요청 전 잔액이 80 이상이어야 합니다. 다른 동기 API와 팀 동시 실행 한도를 공유합니다(Starter/유효 구독 없음 1, Standard 5, Premium 10). 대시보드 기록이나 webhook은 생성하지 않습니다.

응답 예시입니다. 필드 제공 여부는 계정의 공개 정보에 따라 달라집니다.

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.instagram.com/lunacut.edit/",
    "channelAbout": {
      "platform": 6,
      "platform_name": "instagram",
      "username": "lunacut.edit",
      "channel_url": "https://www.instagram.com/lunacut.edit/",
      "country": "Brazil",
      "country_visible": true,
      "date_joined": "2020-05",
      "date_joined_text": "May 2020"
    }
  }
}

country: 공개 국가/지역(country_visible=true일 때만 반환), 실시간 IP 위치가 아닙니다. country_visible: 공개 여부, 알 수 없으면 null. date_joined: 가입 연월(YYYY-MM), 없거나 해석할 수 없으면 null. date_joined_text: 원본 가입 시점 텍스트, 없으면 null. Bio, 팔로워 수, 이전 사용자 이름은 포함하지 않습니다.

400 / 401 / 402 / 403 / 429 (Retry-After: 1) / 502 / 503 / 504.

웹훅 연동

SNSTracker는 모니터링된 콘텐츠가 설정한 임계값을 충족할 때 실시간 알림을 받기 위해 웹훅을 지원합니다. 다음에 대한 알림을 받을 수 있도록 웹훅을 구성할 수 있습니다:

  • 피드 업데이트: 조회수, 참여도(좋아요 + 댓글 + 공유)가 임계값만큼 증가할 때
  • 채널 업데이트: 팔로워, 팔로잉, 좋아요가 임계값만큼 증가할 때

웹훅 설정하기

  1. 컬렉션 설정에서 웹훅 대상을 구성
  2. 컬렉션 구성에서 알림 활성화
  3. 모니터링할 지표의 임계값 설정

자세한 웹훅 구성 지침은 웹훅 구성 가이드를 참고하세요.

오류 응답

모든 엔드포인트는 다음 오류 응답을 반환할 수 있습니다:

401 Unauthorized - API 키 누락

{
  "code": -1,
  "message": "X-API-Key header is required"
}

401 Unauthorized - 잘못된 API 키

{
  "code": -1,
  "message": "Invalid API key"
}

400 Bad Request - 잘못된 입력

{
  "code": -1,
  "message": "Invalid request: urls must be an array"
}

400 Bad Request - URL 과다(피드 생성)

{
  "code": -1,
  "message": "Maximum 200 URLs allowed per request"
}

400 Bad Request - URL 과다(채널 생성)

{
  "code": -1,
  "message": "Maximum 200 URLs allowed per request"
}

400 Bad Request - 크레딧 부족

{
  "code": -1,
  "message": "Insufficient credits. Required: 10, Available: 5"
}

429 Too Many Requests - 팀 동기화 동시 실행 한도

{
  "code": -1,
  "message": "Maximum concurrent sync requests (1) reached for this team. Currently active: 1. Wait for a request to complete, or contact official support to increase the limit."
}

403 Forbidden - 잘못된 컬렉션

{
  "code": -1,
  "message": "Collection not found or does not belong to your team"
}

404 Not Found

{
  "code": -1,
  "message": "No feeds found"
}

또는

{
  "code": -1,
  "message": "No channels found"
}

사용 예시

Python 예시 - 피드 생성

import requests

url = "https://snstracker.com/api/v1/feeds"
headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
}
data = {
    "urls": [
        "https://www.tiktok.com/@user/video/1234567890",
        "https://www.instagram.com/p/ABC123/"
    ]
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result["code"] == 0:
    print(f"Successfully created {result['data']['success']} feeds")
    for feed in result["data"]["results"]:
        print(f"  - {feed['url']}: {feed['feedId']}")
else:
    print(f"Error: {result['message']}")

JavaScript 예시 - 피드 새로고침

const response = await fetch('https://snstracker.com/api/v1/feeds/refresh', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    feedIds: ['feed_abc123xyz', 'feed_def456uvw'],
  }),
});

const result = await response.json();

if (result.code === 0) {
  console.log(`Successfully refreshed ${result.data.total} feeds`);
  result.data.feedIds.forEach((feedId) => {
    console.log(`  - ${feedId}`);
  });
} else {
  console.error(`Error: ${result.message}`);
}

중요 사항

  1. URL 검증: 모든 URL은 생성 전에 자동으로 검증됩니다. 유효하지 않은 URL은 거부됩니다.

  2. 중복 항목: 동일한 URL을 가진 항목이 컬렉션에 이미 존재하는 경우:

    • 활성 상태이면 건너뜁니다(skipped: true로 표시)
    • 중지 상태이면 재개됩니다(resumed: true로 표시)

  3. 데이터 수집: 생성 성공 후 항목은 데이터 수집을 위해 대기열에 추가됩니다. 데이터는 생성 후 곧 사용할 수 있습니다.

  4. 새로고침 상태: 상태가 "Pending" 또는 "Tracked"인 항목만 새로고침할 수 있습니다. 그 외 상태의 항목은 필터링됩니다.

  5. 크레딧: 요청 전에 충분한 크레딧이 있는지 확인하세요. 동기화 작업은 데이터 조회 성공 시 즉시 크레딧을 소모합니다. Xiaohongshu channel tasks are priced separately and currently cost 10 credits per successful request. /api/v1/channels/feeds/sync: 성공적으로 조회한 페이지는 빈 페이지를 포함하여 페이지당 10 크레딧입니다. 실패한 요청만 무료이며 요청 전 최소 10 크레딧이 필요합니다. 다른 동기화 API와 팀 동시 실행 한도를 공유하고 대시보드 기록은 만들지 않습니다. /api/v1/channels/about/sync: 성공 요청당 80 크레딧이 차감되며 추가 필드가 null이어도 과금됩니다. 오류는 과금하지 않으며 요청 전 잔액이 80 이상이어야 합니다. 다른 동기 API와 팀 동시 실행 한도를 공유합니다(Starter/유효 구독 없음 1, Standard 5, Premium 10). 대시보드 기록이나 webhook은 생성하지 않습니다.

  6. 팀 동기화 동시 실행 한도 (/api/v1/feeds/sync + /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync): 같은 팀의 모든 구성원, API 키, 모든 동기화 엔드포인트는 하나의 동시 실행 한도를 공유합니다. 공유 한도는 스타터 또는 유효한 구독이 없으면 1개, 스탠다드는 5개, 프리미엄은 10개입니다. 현재 유효한 구독에 따라 자동 적용되며, 공식 지원팀이 설정한 팀별 한도가 있으면 해당 설정이 우선합니다. 팀 한도를 늘리려면 공식 지원팀에 문의하세요.

  7. 동기화 vs 생성: 동기화 엔드포인트(/api/v1/feeds/sync 및 /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync)는 독립형이며 웹 플랫폼과 연동되지 않습니다. API 응답에서만 데이터를 반환하고 대시보드에 레코드를 생성하지 않습니다. 웹 플랫폼에 표시되는 지속적인 모니터링 항목을 생성하려면 생성 엔드포인트(/api/v1/feeds 및 /api/v1/channels)를 사용하세요.

  8. 재시도: 429 응답을 받으면 진행 중인 요청이 완료될 때까지 기다린 뒤 Retry-After를 지키며 재시도 간격을 늘리세요. 503 응답은 나중에 재시도하세요.

  9. 지원 플랫폼: TikTok, Instagram, YouTube 및 기타 주요 소셜 미디어 플랫폼.

문제 해결

문제: "X-API-Key header is required"
해결: 요청에 X-API-Key 헤더를 포함했는지 확인하세요.

문제: "Invalid API key"
해결: API 키가 올바른지 확인하세요. 설정 → API 키에서 새로 생성할 수 있습니다.

문제: "Maximum URLs allowed per request"
해결: URL을 여러 요청으로 나누세요. 피드는 요청당 최대 200개, 채널은 요청당 최대 5개 URL을 허용합니다.

문제: "No collection found"
해결: 대시보드에서 먼저 컬렉션을 생성하거나 기존 컬렉션 ID를 지정하세요.

문제: "Insufficient credits"
해결: 크레딧을 추가 구매하거나 구독 요금제를 확인하세요.

문제: "No refreshable items found"
해결: 상태가 "Pending" 또는 "Tracked"인 항목만 새로고침할 수 있습니다. 항목 상태를 확인하세요.

문제: 일부 URL이 검증에 실패함
해결: 응답의 errors 배열에서 구체적인 오류 메시지를 확인하세요. 지원되는 플랫폼의 공개 접근 가능한 URL인지 확인하세요.

웹훅 설정 가이드

Next Page

On this page

개요
인증
API 엔드포인트
1. 피드 생성
요청
응답
요청 예시
2. 피드 새로고침
요청
응답
요청 예시
3. 채널 생성
요청
응답
요청 예시
4. 채널 새로고침
요청
응답
요청 예시
5. 피드 동기화
요청
응답
요청 예시
6. 채널 동기화
요청
응답
요청 예시
7. 채널 콘텐츠 동기화
Request and pagination
Response example (placeholder cursor) — reels, lunacut.edit, count=1
8. 프로필 추가 정보 조회
웹훅 연동
웹훅 설정하기
오류 응답
401 Unauthorized - API 키 누락
401 Unauthorized - 잘못된 API 키
400 Bad Request - 잘못된 입력
400 Bad Request - URL 과다(피드 생성)
400 Bad Request - URL 과다(채널 생성)
400 Bad Request - 크레딧 부족
429 Too Many Requests - 팀 동기화 동시 실행 한도
403 Forbidden - 잘못된 컬렉션
404 Not Found
사용 예시
Python 예시 - 피드 생성
JavaScript 예시 - 피드 새로고침
중요 사항
문제 해결