> ## Documentation Index
> Fetch the complete documentation index at: https://outcrawl.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Official TypeScript SDK for Outcrawl. Zero runtime dependencies, native fetch, and the only client with live browser control.

export const OutcrawlStyles = () => {
  if (typeof document !== 'undefined' && !document.getElementById('outcrawl-overrides')) {
    const s = document.createElement('style');
    s.id = 'outcrawl-overrides';
    s.textContent = `
      /* Match the product's radius grid (4 / 6 / 8 / 9999), not Mintlify's default. */
      .rounded-sm { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-md { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-lg { border-radius: 0.5rem !important; }   /* 8px, --r-panel */
      .rounded-l-sm { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-sm { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-md { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-md { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-lg { border-top-left-radius: 0.5rem !important; border-bottom-left-radius: 0.5rem !important; }
      .rounded-r-lg { border-top-right-radius: 0.5rem !important; border-bottom-right-radius: 0.5rem !important; }

      /* Cards: never pure white in light mode, matching the one-big-card surface tone. */
      .card { background-color: #fcfcfc !important; border-radius: 0.5rem !important; }
      html.dark .card { background-color: #141311 !important; }

      /* Docs hero box */
      .oc-hero { background-color: #fcfcfc; border: 1px solid #e5e2dc; }
      html.dark .oc-hero { background-color: #141311; border-color: #26241f; }
      html.dark .oc-hero h1 { color: #edeae4; }

      /* Thin, transparent-track, hide-until-hover scrollbar. */
      ::-webkit-scrollbar { width: 6px; height: 6px; background-color: transparent; }
      ::-webkit-scrollbar-track { background-color: transparent; }
      ::-webkit-scrollbar-thumb { background-color: rgba(155, 155, 155, 0.5); border-radius: 10px; transition: opacity 0.3s ease; opacity: 0; }
      ::-webkit-scrollbar-thumb:hover { background-color: rgba(155, 155, 155, 0.7); }
      *:hover::-webkit-scrollbar-thumb,
      *:focus::-webkit-scrollbar-thumb,
      *:active::-webkit-scrollbar-thumb { opacity: 1; }
      * { scrollbar-width: thin; scrollbar-color: rgba(155, 155, 155, 0.5) transparent; }
    `;
    document.head.appendChild(s);
  }
  return null;
};

<OutcrawlStyles />

The official TypeScript client. Zero runtime dependencies: Playwright is an optional peer, reached only through a dynamic import, so a caller who never opens a browser never installs it.

## Installation

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
npm install @outcrawl/sdk
```

## Quick start

```typescript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
import { Outcrawl } from '@outcrawl/sdk';

const oc = new Outcrawl(); // reads OUTCRAWL_API_KEY; pass { apiKey } to override

const doc = await oc.scrape('https://example.com', { formats: ['markdown'] });
console.log(doc.usage); // every call returns what it cost, on the result that caused it
```

## Configuration

| Variable | Meaning | Default |
| - | - | - |
| `OUTCRAWL_API_KEY` | Your key | Required unless `apiKey` is passed |
| `OUTCRAWL_API_URL` | Base URL | `https://api.outcrawl.ai/v1` |

## Scrape, crawl, search

```typescript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
const doc = await oc.scrape('https://example.com', { formats: ['markdown'] });

for await (const page of await oc.crawl('https://example.com')) {
  console.log(page.url, page.markdown);
}

const results = await oc.search('outcrawl');
```

`await oc.crawl(url)` gives you a crawl to iterate: it streams every page as it is fetched, rather than waiting for the whole site. `oc.crawl.job(id)` reaches a crawl by id if the stream drops.

## Live browsers, TypeScript only

The one thing that does not exist in the Python SDK. `oc.browser()` allocates a session on the fleet and connects to it over CDP, nothing launches locally, and every request already leaves from a residential exit. You bring no infrastructure of your own to run.

```typescript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
const profile = await oc.profiles.create({ label: 'demo-user-42' }); // minted once, reused by id
const browser = await oc.browser({ profile: profile.id });           // its cookies and logins persist
const page = await browser.newPage();
await page.goto('https://practicetestautomation.com/practice-test-login/'); // a public demo login
await page.fill('#username', 'student');     // human input model, the default
await page.fill('#password', 'Password123');
await page.click('#submit');
await page.raw.waitForURL('**/logged-in-successfully/');
console.log(await page.title());             // "Logged In Successfully | Practice Test Automation"
await browser.close();
```

`BrowserOptions` is exactly `{ profile, proxy, record }`. See [browsers](/docs/browsers/overview) and [human input](/docs/browsers/human-input) for what `click`, `fill`, `type`, `hover`, `press` and `selectOption` actually do by default, and why it matters.

## Agents

```typescript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
const run = oc.agent({
  task: 'Report the title of the top story on Hacker News.',
  caps: { budget: '16.00' },
});
const result = await run;         // await for the settled result
console.log(result.data);
for await (const step of run) {}  // or iterate the event log, both on one job is fine
```

`caps.budget` is required, both at the type level and at runtime, a hard ceiling on what the run is billed. `caps.steps` and `caps.duration` are optional. A budget at or below the price of one page (1 credit) is refused before the run starts.

Give `agent` a JSON Schema and `result.data` comes back shaped to it instead of free text:

```typescript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
const typed = await oc.agent({
  task: 'Report the title of the top story on Hacker News.',
  caps: { steps: 20, budget: '16.00', duration: '5m' },
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
});
if (typed.status === 'completed') console.log(typed.data); // { title: '...' }
else console.log(typed.status, typed.stopReason);          // capped, partial or failed: data may be absent
```

An `AgentJob` also carries `status()`, `results()`, `events()`, `cancel()`, `control('take' | 'release', who?)`, `answer(answer, answeredBy?)` and `addFile({ name, bytes, contentType? })`. See [agents](/docs/agents/overview) for what each one is for.

## Platform primitives

`oc.sessions`, `oc.profiles`, `oc.monitors`, `oc.secrets`, `oc.rules`, `oc.integrations` and `oc.credits()` all follow the shapes documented under [account](/docs/account/profiles) and [billing](/docs/billing/credits).

## Errors

Every error class `errorFromWire` can produce is exported: `OutcrawlError`, `BadRequestError`, `CapExceededError`, `CapabilityUnavailableError`, `ConcurrencyLimitError`, `NoCapacityError`, `NotFoundError`, `PlanRequiredError`, `ProfileInUseError`, `ProfileNotFoundError`, `QuotaExceededError`, `UnauthorizedError` and more, plus `isOutcrawlError` and `isKnownErrorCode`. Branch on `error.code`, never on `error.message`. See [errors](/docs/api/errors) for the full 31-code table.

## Testing an unmodified Playwright script

The SDK is ergonomics, never the only door. A plain Playwright script pointed at the CDP endpoint `oc.browser()` opens keeps working without it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.