Use SocialCrawl with 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.
pip install openai requests
export SOCIALCRAWL_API_KEY=sc_your_key_here
export OPENROUTER_API_KEY=your_openrouter_key
export OPENROUTER_MODEL=your_chosen_modelConnect
Declare each tool in the chat completions format, run what the model asks for, and send each result back as a tool message.
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.
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 and Credits.
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.
