Run a service

POST

{platform}

{service}

curl -X POST https://api.socialrouter.io/v1/reddit/subreddit.posts \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.reddit.com/r/programming",
    "limit": 50,
    "options": { "sort": "top", "time": "week" }
  }'

const response = await fetch(
  "https://api.socialrouter.io/v1/reddit/subreddit.posts",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sr_live_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://www.reddit.com/r/programming",
      limit: 50,
      options: { sort: "top", time: "week" },
    }),
  },
);

import requests

response = requests.post(
    "https://api.socialrouter.io/v1/reddit/subreddit.posts",
    headers={"Authorization": "Bearer sr_live_your_key"},
    json={
        "url": "https://www.reddit.com/r/programming",
        "limit": 50,
        "options": {"sort": "top", "time": "week"},
    },
)

const run = await sr.run("reddit/subreddit.posts", {
  url: "https://www.reddit.com/r/programming",
  limit: 50,
  options: { sort: "top", time: "week" },
});

{
  "id": "ext_a1b2c3d4",
  "status": "completed",
  "platform": "linkedin",
  "service": "profile.info",
  "url": "https://www.linkedin.com/in/satyanadella",
  "served_by": "brightdata/linkedin",
  "credits_used": 0.001725,
  "data": [
    {
      "name": "Satya Nadella",
      "title": "Chairman and CEO at Microsoft",
      "company": "Microsoft",
      "location": "Redmond, Washington",
      "profile_url": "https://www.linkedin.com/in/satyanadella",
      "source": "linkedin",
      "extracted_at": "2026-07-30T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "returned": 1
  },
  "created_at": "2026-07-30T12:00:00Z",
  "completed_at": "2026-07-30T12:00:01Z"
}

{
  "id": "ext_a1b2c3d4",
  "status": "completed",
  "platform": "reddit",
  "service": "subreddit.posts",
  "url": "https://www.reddit.com/r/programming",
  "served_by": "apify/trudax",
  "fallback_from": "apify/harshmaur",
  "credits_used": 0.276,
  "data": [/* … */],
  "pagination": { "total": 50, "returned": 50 },
  "created_at": "2026-07-30T12:00:00Z",
  "completed_at": "2026-07-30T12:00:22Z"
}

{
  "error": {
    "code": "unknown_service",
    "message": "Unknown service \"group.posts\" on reddit. Did you mean \"reddit/subreddit.posts\"? Services on reddit: subreddit.posts, post.info, post.comments.",
    "type": "not_found",
    "did_you_mean": "reddit/subreddit.posts"
  }
}

{
  "error": {
    "code": "unknown_field",
    "message": "Unknown field \"queries\". reddit/subreddit.posts is a URL service, pass 'urls', not 'queries'. Allowed fields: urls, url, provider, limit, options.",
    "type": "validation"
  }
}

{
  "error": {
    "code": "invalid_input_format",
    "message": "This input doesn't match what linkedin/profile.info expects: \"https://www.linkedin.com/company/microsoft\". Expected format: https://www.linkedin.com/in/<handle> (e.g. https://www.linkedin.com/in/williamhgates).",
    "type": "validation",
    "invalid_inputs": ["https://www.linkedin.com/company/microsoft"]
  }
}

{
  "error": {
    "code": "unknown_offer",
    "message": "Offer \"brightdata/reddit\" does not serve reddit/subreddit.posts. Available offers: apify/harshmaur, apify/trudax. Omit 'provider' to let the router pick.",
    "type": "validation",
    "available_offers": ["apify/harshmaur", "apify/trudax"]
  }
}

{
  "error": {
    "code": "invalid_option",
    "message": "Option \"sort\" must be one of: hot, new, top, rising. Received: \"best\".",
    "type": "validation",
    "option": "sort",
    "allowed_values": ["hot", "new", "top", "rising"]
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient balance. Estimated cost up to $0.6500, available: $0.1200. Add credits at your dashboard.",
    "type": "billing"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 42 seconds.",
    "type": "rate_limit"
  }
}

{
  "error": {
    "code": "extraction_failed",
    "message": "Extraction could not be completed.",
    "type": "provider"
  }
}

{
  "error": {
    "code": "request_soft_timeout",
    "message": "Provider stalled, no activity within the soft limit.",
    "type": "timeout"
  }
}

Every service has its own endpoint: POST /v1/reddit/subreddit.posts, POST /v1/linkedin/profile.info, POST /v1/googlemaps/place.search. The path names what you want. The body carries the inputs. Which offer serves it is the router’s job unless you pin one. The call is synchronous: the response is already completed or failed. This page documents the shared contract. For the concrete services, one page per platform lists every endpoint with its accepted inputs, its options, its offers and the fields it returns: LinkedIn, Instagram, X, Reddit, Facebook, TikTok, YouTube, Pinterest, Bluesky, Snapchat, Google Maps.

string

required

One of: linkedin, instagram, x, reddit, facebook, tiktok, youtube, pinterest, bluesky, snapchat, googlemaps.

string

required

A service of that platform, e.g. profile.info, subreddit.posts, place.search. See GET /v1/services for the live list. An unknown service returns 404 with a did-you-mean and the platform’s available services.

string[]

Inputs of a url-kind service. Required for those services, as urls (array) or url (single string).Every URL must match one of the shapes the service declares in accepts[]. Mismatches return 400 invalid_input_format before any routing or billing. Scheme-less URLs that otherwise match are normalized (https:// is prepended).

string

Single-input form of urls.

string[]

Inputs of a query-kind service (place.search, video.search, post.search). Required for those services, as queries (array) or query (single string). Sending urls to a query service, or the reverse, returns a 400 naming the field the service actually takes.

string

Single-input form of queries.

string

Pin one offer, as source/name, e.g. apify/harshmaur or brightdata/reddit. Omit it (the default) to let the router walk the failover chain.Pinning disables failover: the run succeeds or fails on that offer alone. An offer that doesn’t serve this service returns 400 unknown_offer with available_offers.

number

default:"100"

Maximum number of records to return. Integer, 1-250. The cap is sized to fit one offer attempt inside its 120-second deadline. Larger pulls belong to the async API (coming).

object

Typed options declared by the service. See options[] on GET /v1/services/{platform}/{service}. Each option has a type and, for enums, an allowed set.Validation is strict: an unknown key, a wrong type, or an out-of-enum value returns a corrective 400 listing the valid options. Nothing is silently dropped. Options are declared per service, not per offer, so a request stays valid across failover. An offer that doesn’t implement one ignores it.

curl -X POST https://api.socialrouter.io/v1/reddit/subreddit.posts \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.reddit.com/r/programming",
    "limit": 50,
    "options": { "sort": "top", "time": "week" }
  }'

const response = await fetch(
  "https://api.socialrouter.io/v1/reddit/subreddit.posts",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sr_live_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://www.reddit.com/r/programming",
      limit: 50,
      options: { sort: "top", time: "week" },
    }),
  },
);

import requests

response = requests.post(
    "https://api.socialrouter.io/v1/reddit/subreddit.posts",
    headers={"Authorization": "Bearer sr_live_your_key"},
    json={
        "url": "https://www.reddit.com/r/programming",
        "limit": 50,
        "options": {"sort": "top", "time": "week"},
    },
)

const run = await sr.run("reddit/subreddit.posts", {
  url: "https://www.reddit.com/r/programming",
  limit: 50,
  options: { sort: "top", time: "week" },
});

{
  "id": "ext_a1b2c3d4",
  "status": "completed",
  "platform": "linkedin",
  "service": "profile.info",
  "url": "https://www.linkedin.com/in/satyanadella",
  "served_by": "brightdata/linkedin",
  "credits_used": 0.001725,
  "data": [
    {
      "name": "Satya Nadella",
      "title": "Chairman and CEO at Microsoft",
      "company": "Microsoft",
      "location": "Redmond, Washington",
      "profile_url": "https://www.linkedin.com/in/satyanadella",
      "source": "linkedin",
      "extracted_at": "2026-07-30T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "returned": 1
  },
  "created_at": "2026-07-30T12:00:00Z",
  "completed_at": "2026-07-30T12:00:01Z"
}

{
  "id": "ext_a1b2c3d4",
  "status": "completed",
  "platform": "reddit",
  "service": "subreddit.posts",
  "url": "https://www.reddit.com/r/programming",
  "served_by": "apify/trudax",
  "fallback_from": "apify/harshmaur",
  "credits_used": 0.276,
  "data": [/* … */],
  "pagination": { "total": 50, "returned": 50 },
  "created_at": "2026-07-30T12:00:00Z",
  "completed_at": "2026-07-30T12:00:22Z"
}

{
  "error": {
    "code": "unknown_service",
    "message": "Unknown service \"group.posts\" on reddit. Did you mean \"reddit/subreddit.posts\"? Services on reddit: subreddit.posts, post.info, post.comments.",
    "type": "not_found",
    "did_you_mean": "reddit/subreddit.posts"
  }
}

{
  "error": {
    "code": "unknown_field",
    "message": "Unknown field \"queries\". reddit/subreddit.posts is a URL service, pass 'urls', not 'queries'. Allowed fields: urls, url, provider, limit, options.",
    "type": "validation"
  }
}

{
  "error": {
    "code": "invalid_input_format",
    "message": "This input doesn't match what linkedin/profile.info expects: \"https://www.linkedin.com/company/microsoft\". Expected format: https://www.linkedin.com/in/<handle> (e.g. https://www.linkedin.com/in/williamhgates).",
    "type": "validation",
    "invalid_inputs": ["https://www.linkedin.com/company/microsoft"]
  }
}

{
  "error": {
    "code": "unknown_offer",
    "message": "Offer \"brightdata/reddit\" does not serve reddit/subreddit.posts. Available offers: apify/harshmaur, apify/trudax. Omit 'provider' to let the router pick.",
    "type": "validation",
    "available_offers": ["apify/harshmaur", "apify/trudax"]
  }
}

{
  "error": {
    "code": "invalid_option",
    "message": "Option \"sort\" must be one of: hot, new, top, rising. Received: \"best\".",
    "type": "validation",
    "option": "sort",
    "allowed_values": ["hot", "new", "top", "rising"]
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient balance. Estimated cost up to $0.6500, available: $0.1200. Add credits at your dashboard.",
    "type": "billing"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 42 seconds.",
    "type": "rate_limit"
  }
}

{
  "error": {
    "code": "extraction_failed",
    "message": "Extraction could not be completed.",
    "type": "provider"
  }
}

{
  "error": {
    "code": "request_soft_timeout",
    "message": "Provider stalled, no activity within the soft limit.",
    "type": "timeout"
  }
}

Get a runRetrieve the status and results of a past run by ID.

curl -X POST https://api.socialrouter.io/v1/reddit/subreddit.posts \
  -H "Authorization: Bearer sr_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.reddit.com/r/programming",
    "limit": 50,
    "options": { "sort": "top", "time": "week" }
  }'

const response = await fetch(
  "https://api.socialrouter.io/v1/reddit/subreddit.posts",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sr_live_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://www.reddit.com/r/programming",
      limit: 50,
      options: { sort: "top", time: "week" },
    }),
  },
);

import requests

response = requests.post(
    "https://api.socialrouter.io/v1/reddit/subreddit.posts",
    headers={"Authorization": "Bearer sr_live_your_key"},
    json={
        "url": "https://www.reddit.com/r/programming",
        "limit": 50,
        "options": {"sort": "top", "time": "week"},
    },
)

const run = await sr.run("reddit/subreddit.posts", {
  url: "https://www.reddit.com/r/programming",
  limit: 50,
  options: { sort: "top", time: "week" },
});

{
  "id": "ext_a1b2c3d4",
  "status": "completed",
  "platform": "linkedin",
  "service": "profile.info",
  "url": "https://www.linkedin.com/in/satyanadella",
  "served_by": "brightdata/linkedin",
  "credits_used": 0.001725,
  "data": [
    {
      "name": "Satya Nadella",
      "title": "Chairman and CEO at Microsoft",
      "company": "Microsoft",
      "location": "Redmond, Washington",
      "profile_url": "https://www.linkedin.com/in/satyanadella",
      "source": "linkedin",
      "extracted_at": "2026-07-30T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "returned": 1
  },
  "created_at": "2026-07-30T12:00:00Z",
  "completed_at": "2026-07-30T12:00:01Z"
}

{
  "id": "ext_a1b2c3d4",
  "status": "completed",
  "platform": "reddit",
  "service": "subreddit.posts",
  "url": "https://www.reddit.com/r/programming",
  "served_by": "apify/trudax",
  "fallback_from": "apify/harshmaur",
  "credits_used": 0.276,
  "data": [/* … */],
  "pagination": { "total": 50, "returned": 50 },
  "created_at": "2026-07-30T12:00:00Z",
  "completed_at": "2026-07-30T12:00:22Z"
}

{
  "error": {
    "code": "unknown_service",
    "message": "Unknown service \"group.posts\" on reddit. Did you mean \"reddit/subreddit.posts\"? Services on reddit: subreddit.posts, post.info, post.comments.",
    "type": "not_found",
    "did_you_mean": "reddit/subreddit.posts"
  }
}

{
  "error": {
    "code": "unknown_field",
    "message": "Unknown field \"queries\". reddit/subreddit.posts is a URL service, pass 'urls', not 'queries'. Allowed fields: urls, url, provider, limit, options.",
    "type": "validation"
  }
}

{
  "error": {
    "code": "invalid_input_format",
    "message": "This input doesn't match what linkedin/profile.info expects: \"https://www.linkedin.com/company/microsoft\". Expected format: https://www.linkedin.com/in/<handle> (e.g. https://www.linkedin.com/in/williamhgates).",
    "type": "validation",
    "invalid_inputs": ["https://www.linkedin.com/company/microsoft"]
  }
}

{
  "error": {
    "code": "unknown_offer",
    "message": "Offer \"brightdata/reddit\" does not serve reddit/subreddit.posts. Available offers: apify/harshmaur, apify/trudax. Omit 'provider' to let the router pick.",
    "type": "validation",
    "available_offers": ["apify/harshmaur", "apify/trudax"]
  }
}

{
  "error": {
    "code": "invalid_option",
    "message": "Option \"sort\" must be one of: hot, new, top, rising. Received: \"best\".",
    "type": "validation",
    "option": "sort",
    "allowed_values": ["hot", "new", "top", "rising"]
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient balance. Estimated cost up to $0.6500, available: $0.1200. Add credits at your dashboard.",
    "type": "billing"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 42 seconds.",
    "type": "rate_limit"
  }
}

{
  "error": {
    "code": "extraction_failed",
    "message": "Extraction could not be completed.",
    "type": "provider"
  }
}

{
  "error": {
    "code": "request_soft_timeout",
    "message": "Provider stalled, no activity within the soft limit.",
    "type": "timeout"
  }
}

Services

Catalogue

Account

LinkedIn

Instagram

X

Reddit

Facebook

TikTok

YouTube

Pinterest

Bluesky

Snapchat

Google Maps