SocialCrawl

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.

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
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
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.

Resources

On this page