Client reference

Constructor

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

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

Parameter	Type	Required	Default
`apiKey`	`string`	Yes	none
`baseUrl`	`string`	No	`https://api.socialrouter.io`

Running a service

`run(service, input)`

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

Parameter	Type	Required	Description
`service`	`ServiceSlug`	Yes	`"<platform>/<service>"`, e.g. `"linkedin/profile.info"`. A union of every callable service, so an invalid one doesn’t compile.
`input.url` / `input.urls`	`string` / `string[]`	url services	The inputs. `urls` for a batch.
`input.query` / `input.queries`	`string` / `string[]`	query services	The inputs, for query-kind services.
`input.provider`	`${string}/${string}`	No	Pin one offer, e.g. `"apify/harshmaur"`. Omit to let the router fail over.
`input.limit`	`number`	No	Max records (default 100, capped at 250).
`input.options`	typed per service	No	The options that service declares. `Record<string, never>` when it declares none.

The input type is correlated with the service:

await sr.run("googlemaps/place.search", { queries: ["pizza"] });     // ✅
await sr.run("googlemaps/place.search", { urls: ["https://…"] });    // ❌ query service
await sr.run("reddit/subreddit.posts", { url: "…", options: { sort: "best" } }); // ❌ not in the enum

Returns an Extraction:

{
  id: "ext_a1b2c3d4",
  status: "completed",          // "pending" | "completed" | "failed"
  platform: "reddit",
  service: "subreddit.posts",
  url: "https://www.reddit.com/r/programming",
  queries: undefined,           // populated for query-kind services
  served_by: "apify/harshmaur", // the offer that answered, null on failure
  fallback_from: undefined,     // set only when the chain rolled over
  credits_used: 0.138,
  data: ExtractionRecord[],
  pagination: { total: 50, returned: 50 },  // returned < total signals a partial result, the response holds everything the offer produced
  created_at: "2026-07-30T12:00:00Z",
  completed_at: "2026-07-30T12:00:04Z",
}

The call is synchronous: the returned run is already completed or failed.

Typed per-service methods

Every callable service also has a method, grouped by platform, with the same signature as run’s second argument:

await sr.reddit.subredditPosts({ url: "https://www.reddit.com/r/programming" });
await sr.linkedin.profileInfo({ url: "https://linkedin.com/in/alice", options: { includeEmail: false } });
await sr.youtube.channelVideos({ urls: ["https://youtube.com/@mkbhd"] });
await sr.googlemaps.placeSearch({ queries: ["coffee shops in Brooklyn"] });

Method names are the service name in camelCase: subreddit.posts → subredditPosts, profile.info → profileInfo.

Batching

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

Each offer declares its own max_inputs. Offers whose cap is smaller than your batch drop out of the failover chain instead of failing the call.

Pinning an offer

// That offer only, no failover.
await sr.run("reddit/subreddit.posts", {
  url: "https://www.reddit.com/r/programming",
  provider: "apify/trudax",
});

`getExtraction(id)`

const run = await sr.getExtraction("ext_a1b2c3d4");

Catalogue

`listServices(filter?)`

const services = await sr.listServices();
const reddit = await sr.listServices({ platform: "reddit" });
// CatalogueService[]: endpoint, input_kind, input_field, accepts[], options[], offers[]

`getService(service)`

const svc = await sr.getService("reddit/subreddit.posts");
console.log(svc.accepts);  // accepted input shapes, with examples
console.log(svc.options);  // typed options
console.log(svc.offers);   // in failover order, with price_per_record and max_inputs

`listSources()` / `getSource(id)`

const sources = await sr.listSources();
const apify = await sr.getSource("apify");
// SourceInfo: name, description, status, platforms, services_count, offers_count

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: {...} }

by_provider is keyed by offer id ("apify/harshmaur").

Migrating from 0.3.x

0.3.x	0.4.0
`extract({ url, provider: "apify/linkedin/profile.info" })`	`run("linkedin/profile.info", { url })`
`search({ queries, provider: "apify/googlemaps/place.search" })`	`run("googlemaps/place.search", { queries })`
`provider: "apify/reddit/group.posts:trudax"`	`run("reddit/subreddit.posts", { provider: "apify/trudax" })`
`fallback: false`	pin `provider`
`extractAndWait` / `searchAndWait`	`run`, calls are synchronous
`listProviders()` / `getProvider(id)`	`listServices()` / `getService(slug)`, plus `listSources()` for the source view
`result.provider`	`result.served_by`
`result.source` / `result.type`	`result.platform` / `result.service`
`result.kind`	gone, the input kind is a property of the service

Getting started

Reference

Constructor

Running a service

`run(service, input)`

Typed per-service methods

Batching

Pinning an offer

`getExtraction(id)`

Catalogue

`listServices(filter?)`

`getService(service)`

`listSources()` / `getSource(id)`

Account

`getBalance()`

`getUsage(days?)`

Migrating from 0.3.x

​Constructor

​Running a service

​run(service, input)

​Typed per-service methods

​Batching

​Pinning an offer

​getExtraction(id)

​Catalogue

​listServices(filter?)

​getService(service)

​listSources() / getSource(id)

​Account

​getBalance()

​getUsage(days?)

​Migrating from 0.3.x

Constructor

Running a service

`run(service, input)`

Typed per-service methods

Batching

Pinning an offer

`getExtraction(id)`

Catalogue

`listServices(filter?)`

`getService(service)`

`listSources()` / `getSource(id)`

Account

`getBalance()`

`getUsage(days?)`

Migrating from 0.3.x