SNSTrackerSNSTracker

API Reference

Overview

The SNSTracker API allows you to programmatically manage monitoring feeds and channels. You can create feeds (videos, posts, etc.) and channels (accounts, profiles), refresh them to get the latest data, and receive real-time notifications via webhooks.

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header.

How to get your API key:

  1. Log in to SNSTracker
  2. Go to Settings → API Keys
  3. Create a new API key or use an existing one
  4. Copy the API key (you'll only see it once when created)

API Endpoints

1. Create Feeds

Create monitoring feeds by submitting feed URLs (videos, posts, etc.).

POST /api/v1/feeds

Request

Headers:

  • X-API-Key: Your API key (required)
  • Content-Type: application/json

Request Body:

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

Parameters:

  • urls (required): Array of feed URLs to monitor. Maximum 200 URLs per request.
  • collectionId (optional): Collection ID where feeds will be added. If not provided, your team's default collection will be used.

Response

Success Response (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": "Feeds created successfully. Data will be updated shortly."
  }
}

Response Fields:

  • success: Number of successfully created feeds
  • failed: Number of failed feed creations
  • total: Total number of URLs provided
  • results: Array of results for each URL
    • index: Zero-based index in the request array
    • url: The validated and standardized URL
    • platform: Detected platform (tiktok, instagram, youtube, etc.)
    • feedId: Unique identifier of the created feed
    • success: Whether the feed was created successfully
    • skipped: (optional) Whether the feed was skipped because it already exists
    • resumed: (optional) Whether a stopped feed was resumed
    • error: (optional) Error message if creation failed
  • errors: Array of errors for failed URLs

Example Request

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. Refresh Feeds

Refresh existing feeds to get the latest data immediately. Only feeds with status "Pending" or "Tracked" can be refreshed.

POST /api/v1/feeds/refresh

Request

Headers:

  • X-API-Key: Your API key (required)
  • Content-Type: application/json

Request Body:

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

Parameters:

  • feedIds (required): Array of feed IDs to refresh

Response

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "feedIds": ["feed_abc123xyz", "feed_def456uvw"],
    "total": 2,
    "message": "Successfully refreshed 2 feed(s)"
  }
}

Response Fields:

  • success: Whether the refresh operation was successful
  • feedIds: Array of feed IDs that were refreshed
  • total: Number of feeds refreshed
  • message: Success message

Example Request

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. Create Channels

Create monitoring channels by submitting channel URLs (account profiles, etc.).

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

Request

Headers:

  • X-API-Key: Your API key (required)
  • Content-Type: application/json

Request Body:

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

Parameters:

  • urls (required): Array of channel URLs to monitor. Maximum 200 URLs per request.
  • collectionId (optional): Collection ID where channels will be added. If not provided, your team's default collection will be used.

Response

Success Response (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": "Channels created successfully. Data will be updated shortly."
  }
}

Response Fields:

  • success: Number of successfully created channels
  • failed: Number of failed channel creations
  • total: Total number of URLs provided
  • results: Array of results for each URL
    • index: Zero-based index in the request array
    • url: The validated and standardized URL
    • platform: Detected platform (tiktok, instagram, youtube, etc.)
    • channelId: Unique identifier of the created channel
    • success: Whether the channel was created successfully
    • skipped: (optional) Whether the channel was skipped because it already exists
    • resumed: (optional) Whether a stopped channel was resumed
    • error: (optional) Error message if creation failed
  • errors: Array of errors for failed URLs

Example Request

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. Refresh Channels

Refresh existing channels to get the latest data immediately. Only channels with status "Pending" or "Tracked" can be refreshed.

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

Request

Headers:

  • X-API-Key: Your API key (required)
  • Content-Type: application/json

Request Body:

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

Parameters:

  • channelIds (required): Array of channel IDs to refresh

Response

Success Response (200):

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "channelIds": ["channel_abc123xyz", "channel_def456uvw"],
    "total": 2,
    "message": "Successfully refreshed 2 channel(s)"
  }
}

Response Fields:

  • success: Whether the refresh operation was successful
  • channelIds: Array of channel IDs that were refreshed
  • total: Number of channels refreshed
  • message: Success message

Example Request

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. Sync Feed

Sync feed data directly from the scrapy service. This endpoint fetches the latest feed data immediately and consumes credits upon successful sync. All members and API keys of a team share one concurrency limit across all sync endpoints. The shared limit is 1 for Starter or no active subscription, 5 for Standard, and 10 for Premium.

⚠️ Important Note: This sync endpoint is standalone and does NOT integrate with the web platform. Sync operations will:

  • NOT create or update feed records in the web dashboard
  • NOT appear in your feeds list or collections
  • NOT trigger webhooks or notifications
  • ONLY return the fetched data directly in the API response

This endpoint is designed for one-time data retrieval via API. To create persistent monitoring feeds that appear in the web platform, use the Create Feeds endpoint instead.

POST /api/v1/feeds/sync

Request

Headers:

  • X-API-Key: Your API key (required)
  • Content-Type: application/json

Request Body:

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

Parameters:

  • url (required): Feed URL to sync. Must be a valid, non-empty string.

Response

Success Response (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": "Video description",
      "hashtags": ["tag1", "tag2"],
      "publish_at": 1234567890
    }
  }
}

Response Fields:

  • success: Whether the sync operation was successful
  • url: The synced feed URL
  • feedInfo: Complete feed information including metrics, description, hashtags, etc.

Error Responses:

  • 429 Too Many Requests: The shared team concurrency limit is reached. The request is not queued.
  • 400 Bad Request: Insufficient credits or invalid URL

Example Request

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. Sync Channel

Sync channel data directly from the scrapy service. This endpoint fetches the latest channel data immediately and consumes credits upon successful sync. All members and API keys of a team share one concurrency limit across all sync endpoints. The shared limit is 1 for Starter or no active subscription, 5 for Standard, and 10 for Premium.

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

⚠️ Important Note: This sync endpoint is standalone and does NOT integrate with the web platform. Sync operations will:

  • NOT create or update channel records in the web dashboard
  • NOT appear in your channels list or collections
  • NOT trigger webhooks or notifications
  • ONLY return the fetched data directly in the API response

This endpoint is designed for one-time data retrieval via API. To create persistent monitoring channels that appear in the web platform, use the Create Channels endpoint instead.

POST /api/v1/channels/sync

Request

Headers:

  • X-API-Key: Your API key (required)
  • Content-Type: application/json

Request Body:

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

Parameters:

  • url (required): Channel URL to sync. Must be a valid, non-empty string.

Response

Success Response (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": "Channel description",
      "followers": 1000000,
      "followings": 2000,
      "likes": 200000000,
      "total_count": 1000,
      "track_count": 1000,
      "status": 1
    }
  }
}

Response Fields:

  • success: Whether the sync operation was successful
  • url: The synced channel URL
  • channelInfo: Complete channel information including metrics, description, etc.

Error Responses:

  • 429 Too Many Requests: The shared team concurrency limit is reached. The request is not queued.
  • 400 Bad Request: Insufficient credits or invalid URL

Example Request

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. Sync Channel Content

Returns one page of channel content. Instagram and Reels return at most 12 items per request, with no automatic pagination. instagram returns Posts (images, videos and carousels); reels returns Reels videos.

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 is an optional positive integer specifying the desired number of items on this page, with no default value. Limits vary by platform: Instagram and Reels return at most 12 items per request, and may return fewer. Omit it to use the platform’s default page size.
  • Omit cursor for the first page. Pass the previous next_cursor unchanged for the next page, keeping platform and channel_name unchanged. When there is no next page: has_more=false, next_cursor=null.
{
  "platform": "instagram",
  "channel_name": "instagram",
  "cursor": "previous-next-cursor"
}

Each successful page costs 10 credits, including empty pages. Only failed requests are free; a balance of at least 10 credits is required before requesting a page. Each page shares the team concurrency limit with the other sync endpoints. No dashboard records are created.

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.

Metrics in items, including views (view_count), likes (like_count), saves (bookmark_count) and comments (comment_count), depend on the platform and its channel-list response. Some metrics may be unavailable. Unavailable metrics are returned as null, which does not mean zero.

To look up metrics missing from the channel list, call POST /api/v1/feeds/sync separately with the item’s url as the request body’s url. This detail request is billed separately under that endpoint’s rules. Results still depend on the data the platform provides; not all missing metrics can necessarily be retrieved.

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.

Webhook Integration

SNSTracker supports webhooks to receive real-time notifications when monitored content meets your configured thresholds. You can configure webhooks to receive notifications about:

  • Feed updates: When views, engagement (likes + comments + shares) increase by your threshold
  • Channel updates: When followers, followings, or likes increase by your threshold

Setting Up Webhooks

  1. Configure webhook targets in your Collections settings
  2. Enable notifications in your Collection configuration
  3. Set thresholds for metrics you want to monitor

For detailed webhook configuration instructions, please refer to the Webhook Configuration Guide.

Error Responses

All endpoints may return the following error responses:

401 Unauthorized - Missing API Key

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

401 Unauthorized - Invalid API Key

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

400 Bad Request - Invalid Input

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

400 Bad Request - Too Many URLs (Create Feeds)

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

400 Bad Request - Too Many URLs (Create Channels)

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

400 Bad Request - Insufficient Credits

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

429 Too Many Requests - Team Sync Concurrency

{
  "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 - Invalid Collection

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

404 Not Found

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

or

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

Usage Examples

Python Example - Create Feeds

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 Example - Refresh Feeds

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}`);
}

Important Notes

  1. URL Validation: All URLs are automatically validated before creation. Invalid URLs will be rejected.

  2. Duplicate Items: If an item with the same URL already exists in the collection:

    • If it's active, it will be skipped (marked with skipped: true)
    • If it's stopped, it will be resumed (marked with resumed: true)

  3. Data Collection: After successful creation, items are queued for data collection. Data will be available shortly after creation.

  4. Refresh Status: Only items with status "Pending" or "Tracked" can be refreshed. Items with other statuses will be filtered out.

  5. Credits: Make sure you have sufficient credits before making requests. Sync operations consume credits immediately upon successful data retrieval. Xiaohongshu channel tasks are priced separately and currently cost 10 credits per successful request. /api/v1/channels/feeds/sync: Each successful page costs 10 credits, including empty pages. Only failed requests are free; a balance of at least 10 credits is required before requesting a page. Each page shares the team concurrency limit with the other sync endpoints. No dashboard records are created.

  6. Team Sync Concurrency (/api/v1/feeds/sync + /api/v1/channels/sync + /api/v1/channels/feeds/sync): All members and API keys of a team share one concurrency limit across all sync endpoints. The shared limit is 1 for Starter or no active subscription, 5 for Standard, and 10 for Premium. The limit follows the currently effective subscription; an official team-specific setting takes precedence. To increase your team's limit, contact official support.

  7. Sync vs Create: The sync endpoints (/api/v1/feeds/sync and /api/v1/channels/sync + /api/v1/channels/feeds/sync) are standalone and do NOT integrate with the web platform. They only return data in the API response and do not create records in the dashboard. To create persistent monitoring items that appear in the web platform, use the Create endpoints (/api/v1/feeds and /api/v1/channels) instead.

  8. Retries: After 429, wait for an active request to finish and retry with backoff, respecting Retry-After. After 503, retry later.

  9. Supported Platforms: TikTok, Instagram, YouTube, and other major social media platforms.

Troubleshooting

Issue: "X-API-Key header is required"
Solution: Make sure you include the X-API-Key header in your request.

Issue: "Invalid API key"
Solution: Verify your API key is correct. You can create a new one from Settings → API Keys.

Issue: "Maximum URLs allowed per request"
Solution: Split your URLs into multiple requests. Feeds and channels both allow up to 200 URLs per request.

Issue: "No collection found"
Solution: Create a collection first in the dashboard, or specify an existing collection ID.

Issue: "Insufficient credits"
Solution: Purchase more credits or check your subscription plan.

Issue: "No refreshable items found"
Solution: Only items with status "Pending" or "Tracked" can be refreshed. Check the status of your items.

Issue: Some URLs fail validation
Solution: Check the errors array in the response for specific error messages. Make sure URLs are from supported platforms and are publicly accessible.

Webhook Configuration Guide

Next Page

On this page

Overview
Authentication
API Endpoints
1. Create Feeds
Request
Response
Example Request
2. Refresh Feeds
Request
Response
Example Request
3. Create Channels
Request
Response
Example Request
4. Refresh Channels
Request
Response
Example Request
5. Sync Feed
Request
Response
Example Request
6. Sync Channel
Request
Response
Example Request
7. Sync Channel Content
Request and pagination
Response example (placeholder cursor) — reels, lunacut.edit, count=1
Webhook Integration
Setting Up Webhooks
Error Responses
401 Unauthorized - Missing API Key
401 Unauthorized - Invalid API Key
400 Bad Request - Invalid Input
400 Bad Request - Too Many URLs (Create Feeds)
400 Bad Request - Too Many URLs (Create Channels)
400 Bad Request - Insufficient Credits
429 Too Many Requests - Team Sync Concurrency
403 Forbidden - Invalid Collection
404 Not Found
Usage Examples
Python Example - Create Feeds
JavaScript Example - Refresh Feeds
Important Notes
Troubleshooting