Utility Endpoint Usage Guide API

{
  "success": true,
  "platform": "utility",
  "endpoint": "/v1/utility/endpoint",
  "data": {
    "kind": "endpoint_guide",
    "id": "tiktok/profile",
    "path": "/v1/tiktok/profile",
    "method": "GET",
    "platform": "tiktok",
    "resource": "profile",
    "summary": "Get TikTok user profile",
    "description": "Returns public profile information for a TikTok user: follower count, following count, total likes, bio, avatar URL, and verification status. Pass either `handle` or `user_id`. Profiles behind TikTok's 'audience controls' (a login/age wall in the browser) and private profiles have no publicly readable profile record, so they return `404 RESOURCE_NOT_FOUND` with `error.details.reason` set to `account_private`; those accounts are still live and their posts are still readable through `/v1/tiktok/profile/videos` with the same handle. A handle the platform reports as unused returns the same status with `reason` set to `account_gone`; because TikTok numeric ids are permanent, re-running the lookup with `user_id` tells a renamed account from a removed one.",
    "credits": {
      "cost": 1,
      "label": "1 (standard)",
      "tier": "standard",
      "pricing_notes": null,
      "billing_rules": [
        "Cache hits cost 0 credits",
        "Failed calls and empty results are automatically refunded"
      ]
    },
    "params": {
      "required": [],
      "one_of": [
        {
          "options": [
            "handle",
            "user_id"
          ],
          "rule": "Provide at least one"
        }
      ],
      "optional": [
        {
          "name": "handle",
          "type": "string",
          "description": "TikTok username without the @ symbol.",
          "example": "charlidamelio",
          "requires": null
        },
        {
          "name": "user_id",
          "type": "string",
          "description": "TikTok numeric user ID. Use this for faster responses.",
          "example": null,
          "requires": null
        }
      ]
    },
    "pagination": null,
    "cache": {
      "ttl_seconds": 900,
      "note": "Identical calls within the TTL are served from cache for 0 credits"
    },
    "response": {
      "archetype": "Author",
      "schema_url": "https://socialcrawl.dev/schemas/author.json",
      "example": {
        "success": true,
        "platform": "tiktok",
        "endpoint": "/v1/tiktok/profile",
        "data": {
          "author": {
            "id": "6917704832925746181",
            "username": "duolingo",
            "display_name": "Duolingo",
            "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/6b2beff1167b40574fcd2ea2caf1444d~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=f3757781&x-expires=1784674800&x-signature=9OCuBINSoeHVQPclR1XuqeA1j%2FE%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
            "bio": "hot owl summer  🔥🦉",
            "verified": true,
            "followers": 17100000,
            "following": 310,
            "posts_count": 1129,
            "likes_count": 482200000,
            "url": null,
            "private": false,
            "joined_at": null
          },
          "computed": {
            "engagement_rate": null,
            "language": null,
            "content_category": "other",
            "estimated_reach": null
          },
          "_warnings": [
            "computed.engagement_rate: author ratio exceeded 1.0 (raw: 28.19883); returned null. A lifetime likes/followers ratio is not a real engagement rate"
          ]
        },
        "credits_used": 1,
        "credits_remaining": 9999,
        "request_id": "req_example000000",
        "cached": false
      },
      "example_source": "archetype"
    },
    "request": {
      "url": "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio",
      "curl": "curl -H \"x-api-key: $SOCIALCRAWL_API_KEY\" \"https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio\""
    },
    "links": {
      "docs": "https://www.socialcrawl.dev/platforms/tiktok/profile",
      "platform_docs": "https://www.socialcrawl.dev/docs/tiktok",
      "llms": "https://www.socialcrawl.dev/llms-tiktok.txt",
      "catalog": "/v1/utility/endpoints?platform=tiktok"
    },
    "related": [
      {
        "id": "tiktok/profile/videos",
        "path": "/v1/tiktok/profile/videos",
        "summary": "List TikTok user videos",
        "how_to_use": "/v1/utility/endpoint?id=tiktok/profile/videos"
      },
      {
        "id": "tiktok/post",
        "path": "/v1/tiktok/post",
        "summary": "Get TikTok post details",
        "how_to_use": "/v1/utility/endpoint?id=tiktok/post"
      },
      {
        "id": "tiktok/post/comments",
        "path": "/v1/tiktok/post/comments",
        "summary": "List TikTok post comments",
        "how_to_use": "/v1/utility/endpoint?id=tiktok/post/comments"
      }
    ],
    "quality": {
      "measured": true,
      "window_days": 7,
      "measured_from": "2026-09-23",
      "measured_to": "2026-09-23",
      "sampled_calls": 1,
      "fill_rate": {
        "author.bio": 1,
        "author.followers": 1,
        "author.likes_count": 1,
        "author.posts_count": 1
      },
      "null_by_design": [],
      "by_rung": [],
      "freshness_hours": null,
      "method": "Production calls made with the endpoint's example inputs, bypassing the cache; fill_rate is the share of returned rows carrying a value for each field over the rolling window, fields that are null by design are listed separately and left out of it, and freshness_hours is the median age of the newest dated row per call."
    }
  },
  "credits_used": 0,
  "request_id": "req_example000000",
  "cached": false
}