​
Constructor

import { SocialRouter } from "@socialrouter/sdk";

const sr = new SocialRouter({
  apiKey: "sr_live_your_key",
  baseUrl: "https://api.socialrouter.io", // optional
});
ParameterTypeRequiredDefault
apiKeystringYes—
baseUrlstringNohttps://api.socialrouter.io

​
Extraction (URL-driven)

​
extract(options)

Start an extraction. Returns immediately with the result (most extractions are synchronous). 
const extraction = await sr.extract({
  url: "https://www.linkedin.com/in/satyanadella",
  provider: "apify/linkedin/profile.info",
  limit: 10, // optional, default 100
});
ParameterTypeRequiredDescription
urlstringone of url/urlsSingle social media URL.
urlsstring[]one of url/urlsBatch list of URLs. Only effective for batch-capable actors — see the providers page.
providerstringYesService slug <provider>/<platform>/<type>[:<tag>] (e.g. apify/linkedin/profile.info or apify/linkedin/profile.posts:apimaestro).
limitnumberNoMax records to return (default 100, capped at 250).
fallbackbooleanNoWhether to walk the provider chain on failure (default true). Set to false to surface the requested provider’s error directly.
Returns an Extraction object: 
{
  id: "ext_a1b2c3d4",
  kind: "extract",           // "extract" | "search"
  status: "completed",       // "pending" | "completed" | "failed"
  source: "linkedin",
  type: "profile.info",
  url: "https://...",
  provider: "apify",
  fallback_from: undefined,  // string — present only when a fallback was used
  credits_used: 0.0065,
  data: ExtractionRecord[],
  pagination: { total: 1, returned: 1, next_cursor: null },
  created_at: "2026-04-10T12:00:00Z",
  completed_at: "2026-04-10T12:00:01Z",
}

​
getExtraction(id)

Retrieve an extraction or search by ID. Useful for polling async results. 
const extraction = await sr.getExtraction("ext_a1b2c3d4");

​
extractAndWait(options, pollIntervalMs?, timeoutMs?)

Convenience method that calls extract() then polls getExtraction() until the status is no longer pending. 
const extraction = await sr.extractAndWait(
  { url: "https://linkedin.com/in/example", provider: "apify/linkedin/profile.info" },
  3000,    // poll every 3s (default)
  120000,  // timeout after 2min (default)
);
Throws an Error if the extraction doesn’t complete within the timeout.

​
Batch URLs

const extraction = await sr.extractAndWait({
  urls: [
    "https://linkedin.com/in/alice",
    "https://linkedin.com/in/bob",
    "https://linkedin.com/in/carol",
  ],
  provider: "apify/linkedin/profile.info",
});

​
Disable fallback

// Fail fast with the requested provider's error — don't walk the chain.
await sr.extract({
  url: "https://linkedin.com/in/example",
  provider: "apify/linkedin/profile.info",
  fallback: false,
});

​
Search (query-driven)

Companion to extract() for services where the input is a search term rather than a URL — currently place.search on Google Maps.

​
search(options)

const result = await sr.search({
  queries: ["coffee shops in Brooklyn", "bakeries in Brooklyn"],
  provider: "apify/googlemaps/place.search",
  limit: 50, // optional, default 100
});
ParameterTypeRequiredDescription
queriesstring[]YesNon-empty list of search queries (terms or context-pinning URLs).
providerstringYesSlug <provider>/<platform>/<type>[:<tag>] whose type is a search type (e.g. apify/googlemaps/place.search).
limitnumberNoPer-query record cap (default 100, capped at 1000).
fallbackbooleanNoWhether to walk the provider chain on failure (default true).
Returns the same Extraction shape as extract() — distinguish via kind === "search". The original queries array is echoed back on the response.

​
searchAndWait(options, pollIntervalMs?, timeoutMs?)

Same polling helper as extractAndWait, but for searches.

​
Providers

​
listProviders()

List all available providers with status and platform coverage. 
const providers = await sr.listProviders();
// ProviderInfo[] — includes supported_search_types when set

​
getProvider(id)

Get details for a specific provider, including extraction and search pricing. 
const provider = await sr.getProvider("apify");
// ProviderDetail — includes pricing[] and (when applicable) search_pricing[]

​
Account

​
getBalance()

const { balance, currency } = await sr.getBalance();
// { balance: 42.5, currency: "USD" }

​
getUsage(days?)

const usage = await sr.getUsage(7);
// { period: "7d", total_requests: 142, total_credits: 55.445, by_provider: {...}, by_platform: {...} }