# OpenRouter (/docs/frameworks/openrouter) Give an OpenRouter agent social media data, with the price shown before it spends. OpenRouter speaks the OpenAI API, so the OpenAI client with OpenRouter's base URL can call SocialCrawl tools through any model that supports tool calling. SocialCrawl publishes no OpenRouter package, and the wrapper below needs none. ## Setup Install the OpenAI client and `requests`, then set your keys. Create the SocialCrawl key in the dashboard under API Keys; it looks like `sc_your_key_here`. Your OpenRouter key goes in `OPENROUTER_API_KEY`, and `OPENROUTER_MODEL` names the model you picked. ```bash title="Terminal" pip install openai requests export SOCIALCRAWL_API_KEY=sc_your_key_here export OPENROUTER_API_KEY=your_openrouter_key export OPENROUTER_MODEL=your_chosen_model ``` ## Connect Declare each tool in the chat completions format, run what the model asks for, and send each result back as a `tool` message. ```python title="Python" import os import requests BASE = "https://www.socialcrawl.dev" HEADERS = {"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]} def estimate_cost(endpoint: str, params: dict) -> dict: """Quote the credits a call will hold. Free. endpoint looks like tiktok/profile.""" r = requests.get( f"{BASE}/v1/utility/estimate", headers=HEADERS, params={"id": endpoint, **params}, timeout=30, ) body = r.json() return body.get("data", body) def call_endpoint(platform: str, resource: str, params: dict) -> dict: """Run one SocialCrawl call, for example tiktok and profile with a handle.""" r = requests.get( f"{BASE}/v1/{platform}/{resource}", headers=HEADERS, params=params, timeout=60 ) body = r.json() if body.get("success"): return body["data"] # Give the model the error type, not the whole envelope. err = body.get("error", {}) return {"error": err.get("type"), "message": err.get("message"), "status": r.status_code} import json from openai import OpenAI client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"]) MODEL = os.environ["OPENROUTER_MODEL"] TOOLS = [ { "type": "function", "function": { "name": "estimate_cost", "description": "Quote the credits a SocialCrawl call will hold. Free. Call it before call_endpoint and tell the user the answer.", "parameters": { "type": "object", "properties": { "endpoint": {"type": "string", "description": "platform/resource, for example tiktok/profile"}, "params": {"type": "object", "description": "The endpoint's query parameters"}, }, "required": ["endpoint", "params"], }, }, }, { "type": "function", "function": { "name": "call_endpoint", "description": "Run one SocialCrawl call, for example platform tiktok and resource profile. Paid, so quote it first. A 402 means out of credits: tell the user and stop.", "parameters": { "type": "object", "properties": { "platform": {"type": "string", "description": "For example tiktok"}, "resource": {"type": "string", "description": "For example profile or profile/videos"}, "params": {"type": "object", "description": "The endpoint's query parameters"}, }, "required": ["platform", "resource", "params"], }, }, }, ] FUNCS = {"estimate_cost": estimate_cost, "call_endpoint": call_endpoint} def run(prompt: str, max_steps: int = 5) -> str: messages = [{"role": "user", "content": prompt}] for _ in range(max_steps): message = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS).choices[0].message if not message.tool_calls: return message.content messages.append(message) for call in message.tool_calls: result = FUNCS[call.function.name](**json.loads(call.function.arguments)) messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)}) return "Stopped at the step limit." ``` ## Read a profile and its posts Quote the call yourself, then run the loop. The estimate is free, and its `hold` is the most the call can take. ```python title="Python" quote = estimate_cost("tiktok/profile", {"handle": "nasa"}) print("hold:", quote["hold"], "valid:", quote["valid"]) print(run("Quote, then read the TikTok profile for nasa and its latest videos, and summarise them.")) ``` ## Keep spend in check Call `estimate_cost` before any paid call and show the answer to the person who owns the key. Keep `max_steps` small, and send `max_credits` on list endpoints so a walk stops where you set it. A 402 means the account is out of credits. Tell the user it is an offer to top up and stop, because a retry cannot succeed. See [Errors](/docs/errors.md) and [Credits](/docs/credits.md). ## Pick a model Choose a model whose listing supports tools. OpenRouter filters the model list for you at `https://openrouter.ai/api/v1/models?supported_parameters=tools`, and a model that ignores tool definitions will answer from memory instead of calling SocialCrawl. ## Resources - [AI agents](/docs/ai-agents.md): Machine-readable references and agent tool files. - [Skills and MCP](/docs/skills-and-mcp.md): The hosted server and agent skill, with no wrapper to write. - [Errors](/docs/errors.md): What each error type means and which are safe to retry. - [Endpoint pricing](/docs/endpoint-pricing.md): The credit price of every endpoint.