Skip to main content

​
1. Get an API key

Sign in to the dashboard and go to Settings → API Keys → Create API key. Copy the sb_live_... value shown in the banner — it’s displayed exactly once. Lose it and you’ll need to mint a new one.
Never commit the key to source control. Put it in a secret manager, an env var, or your deploy pipeline’s secret store. A leaked key lets anyone call the API as you until you revoke it.

​
2. Install the SDK

pip install stablebrowse

​
3. Run your first task

import os
from stablebrowse import Stablebrowse

client = Stablebrowse(api_key=os.environ["STABLEBROWSE_API_KEY"])

result = client.tasks.run(
    end_user_id="alice",
    task="What is the current top story on Hacker News?",
)

print(result.result)
That’s it. The SDK submits the task, polls the server until it completes, and returns the answer. Typical latency: 5-30 seconds for public sites, 10-60 seconds for sites behind logins.

​
4. Ask a follow-up in the same session

The first task minted a session_id on the server. Pass it back to continue the conversation — the agent will have the first answer as context: 
follow_up = client.tasks.run(
    end_user_id="alice",
    task="How many comments does that story have?",
    session_id=result.session_id,
)
print(follow_up.result)

​
5. (Optional) Authenticated platforms

LinkedIn and YouTube work out of the box — no setup, no cookies needed. Twitter, Reddit, TikTok, and Instagram also work out of the box for public, unpersonalised data: stablebrowse supplies default session cookies automatically, so you don’t have to collect anything before your first call. You can optionally upload your end-user’s own cookies to unlock personalised answers (their home feed, their own profile, DMs, watch history, etc.): 
client.end_users("alice").credentials.set(
    twitter_auth_token="...",
    twitter_ct0="...",
)

result = client.tasks.run(
    end_user_id="alice",
    task="Give me the two most recent tweets from @narendramodi.",
)
See Platforms for the full list of supported sites and which cookies each one needs.

​
Where to go next

Concepts

The mental model — businesses, end-users, sessions, tasks.

Authentication

Managing and rotating API keys.

API reference

Direct HTTP — useful if you’re in a language we don’t ship an SDK for yet.

Errors

Every error code the API can return and what to do about it.