Utility API Quickstart API

{
  "success": true,
  "platform": "utility",
  "endpoint": "/v1/utility/quickstart",
  "data": {
    "kind": "quickstart",
    "name": "SocialCrawl API",
    "base_url": "https://www.socialcrawl.dev/v1",
    "auth": {
      "type": "api_key",
      "header": "x-api-key",
      "get_key_url": "https://www.socialcrawl.dev/dashboard/api"
    },
    "first_call": {
      "description": "Get TikTok user profile",
      "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\"",
      "how_to_use": "/v1/utility/endpoint?id=tiktok/profile"
    },
    "envelope": {
      "success": {
        "success": true,
        "platform": "tiktok",
        "endpoint": "profile",
        "data": "... the endpoint's response object ...",
        "credits_used": 1,
        "credits_remaining": 99,
        "request_id": "req_...",
        "cached": false
      },
      "error": {
        "success": false,
        "error": {
          "type": "INSUFFICIENT_CREDITS",
          "message": "... human-readable cause ...",
          "status": 402,
          "doc_url": "https://www.socialcrawl.dev/docs/errors#insufficient-credits"
        },
        "credits_used": 0,
        "credits_remaining": 0,
        "request_id": "req_..."
      }
    },
    "billing": {
      "model": "credits",
      "tiers": {
        "standard": 1,
        "advanced": 5,
        "premium": 10
      },
      "rules": [
        "Cache hits cost 0 credits",
        "Failed calls and empty results are automatically refunded",
        "Some endpoints have flat or metered pricing; each endpoint's exact cost is in /v1/utility/endpoints"
      ]
    },
    "errors": [
      {
        "code": "MISSING_API_KEY",
        "http": 401,
        "meaning": "No x-api-key header on the request"
      },
      {
        "code": "INVALID_API_KEY",
        "http": 401,
        "meaning": "API key is malformed, not found, revoked, or expired"
      },
      {
        "code": "INSUFFICIENT_CREDITS",
        "http": 402,
        "meaning": "Credit balance is lower than the endpoint cost"
      },
      {
        "code": "INVALID_REQUEST",
        "http": 400,
        "meaning": "A required parameter is missing, a value failed validation, or no one-of group member was provided"
      },
      {
        "code": "ENDPOINT_NOT_FOUND",
        "http": 404,
        "meaning": "The platform or resource is not supported"
      },
      {
        "code": "RESOURCE_NOT_FOUND",
        "http": 404,
        "meaning": "The requested item was not found on the platform; credits are refunded when triggered by an empty upstream result"
      },
      {
        "code": "CONCURRENCY_LIMIT",
        "http": 429,
        "meaning": "More than 50 simultaneous requests on the same API key; honor Retry-After, then back off"
      },
      {
        "code": "UPSTREAM_ERROR",
        "http": 502,
        "meaning": "The platform returned an error; credits are automatically refunded"
      },
      {
        "code": "SERVICE_UNAVAILABLE",
        "http": 503,
        "meaning": "Temporarily unavailable for this platform after repeated failures; retry shortly, credits are refunded"
      },
      {
        "code": "INTERNAL_ERROR",
        "http": 500,
        "meaning": "Unexpected server error; credits are automatically refunded"
      },
      {
        "code": "METHOD_NOT_ALLOWED",
        "http": 405,
        "meaning": "Wrong HTTP method for this endpoint"
      },
      {
        "code": "IDEMPOTENCY_IN_PROGRESS",
        "http": 409,
        "meaning": "Another request with the same key and payload is still running; not charged, retry after Retry-After"
      },
      {
        "code": "IDEMPOTENCY_KEY_CONFLICT",
        "http": 409,
        "meaning": "The Idempotency-Key is already in use by another account"
      },
      {
        "code": "IDEMPOTENCY_REPLAY_UNAVAILABLE",
        "http": 409,
        "meaning": "The completed response for this key exceeded the replay size limit; use a new key to make a new billable request"
      },
      {
        "code": "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH",
        "http": 422,
        "meaning": "The Idempotency-Key was reused with a different request payload"
      },
      {
        "code": "PAYLOAD_TOO_LARGE",
        "http": 413,
        "meaning": "The JSON request body exceeds the 1 MB size limit"
      },
      {
        "code": "RATE_LIMITED",
        "http": 429,
        "meaning": "More than 600 requests in a 1-minute window on the same API key; honor Retry-After, then back off"
      },
      {
        "code": "KEY_BUDGET_EXCEEDED",
        "http": 402,
        "meaning": "This API key has spent its per-key credit limit; the account balance is unaffected. Raise or reset the key's limit in Dashboard → API Keys, or use a key with no limit"
      },
      {
        "code": "COHORT_MEMBER_LIMIT_EXCEEDED",
        "http": 400,
        "meaning": "The member upload would push the cohort past its 10,000-member limit"
      },
      {
        "code": "COHORT_LIMIT_EXCEEDED",
        "http": 400,
        "meaning": "The account already holds the maximum of 100 cohorts; delete one before creating another"
      },
      {
        "code": "COHORT_IDENTITY_PLATFORM_UNSUPPORTED",
        "http": 400,
        "meaning": "That platform is not supported for cohort queries"
      },
      {
        "code": "COHORT_IDENTITY_CONFLICT",
        "http": 409,
        "meaning": "Another external_id already claims that normalized identity in this cohort"
      },
      {
        "code": "COHORT_QUERY_NOT_CANCELLABLE",
        "http": 409,
        "meaning": "The cohort query is already terminal and cannot be cancelled"
      },
      {
        "code": "COHORT_QUERY_NOT_READY",
        "http": 409,
        "meaning": "The cohort query has not reached a terminal state, so its results are not available yet"
      },
      {
        "code": "COHORT_RESULT_TOO_LARGE",
        "http": 413,
        "meaning": "A single stored cohort result cannot fit beneath the 1 MB response-page ceiling"
      }
    ],
    "pagination": {
      "how": "List endpoints return pagination.next_cursor; pass it back as ?cursor=... until has_more is false",
      "params": [
        "cursor"
      ]
    },
    "rate_limits": {
      "requests_per_minute": 600,
      "concurrent_requests": 50
    },
    "stats": {
      "platforms": 65,
      "endpoints": 580
    },
    "next_steps": {
      "catalog": "/v1/utility/endpoints",
      "endpoint_guide": "/v1/utility/endpoint?id=tiktok/profile",
      "agent_context": "/v1/utility/llms",
      "docs": "https://www.socialcrawl.dev/docs",
      "openapi": "https://www.socialcrawl.dev/openapi.json",
      "mcp_server": "npx -y socialcrawl-mcp",
      "agent_skill": "npx skills add socialcrawl/skills"
    }
  },
  "credits_used": 0,
  "request_id": "req_example000000",
  "cached": false
}