SocialCrawl

Use SocialCrawl with Google ADK

Give a Google ADK agent social media data, with the price shown before it spends.

Google's Agent Development Kit turns plain Python functions into agent tools, and it can also attach the hosted SocialCrawl MCP server as a toolset. SocialCrawl publishes no ADK package, and either route needs none.

Setup

Install ADK and requests, then set both keys. Create the SocialCrawl key in the dashboard under API Keys; it looks like sc_your_key_here. The Gemini key goes in GOOGLE_API_KEY.

Terminal
pip install google-adk requests
export SOCIALCRAWL_API_KEY=sc_your_key_here
export GOOGLE_API_KEY=your_gemini_key

Connect

ADK reads an agent from a folder that holds __init__.py with from . import agent, and agent.py with a root_agent. Plain functions in tools are wrapped for you, and the docstring becomes the tool description. The functions take params as a query string such as handle=nasa.

socialcrawl_agent/agent.py
import os

import requests

BASE = "https://www.socialcrawl.dev"
HEADERS = {"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]}


def estimate_cost(endpoint: str, params: str) -> dict:
    """Quote the credits a SocialCrawl call will hold. Free. Call it before call_endpoint.

    Args:
        endpoint: The endpoint as platform/resource, for example tiktok/profile.
        params: The call's query string, for example handle=nasa.
    """
    r = requests.get(
        f"{BASE}/v1/utility/estimate?id={endpoint}&{params}", headers=HEADERS, timeout=30
    )
    body = r.json()
    return body.get("data", body)


def call_endpoint(platform: str, resource: str, params: str) -> dict:
    """Run one SocialCrawl call. Paid, so quote it with estimate_cost first.

    Args:
        platform: For example tiktok.
        resource: For example profile or profile/videos.
        params: The call's query string, for example handle=nasa.
    """
    r = requests.get(
        f"{BASE}/v1/{platform}/{resource}?{params}", headers=HEADERS, timeout=60
    )
    body = r.json()
    if body.get("success"):
        return body["data"]
    err = body.get("error", {})
    return {"error": err.get("type"), "message": err.get("message"), "status": r.status_code}
from google.adk import Agent

root_agent = Agent(
    name="socialcrawl_agent",
    model="gemini-2.5-flash",
    instruction=(
        "Read public social media data with SocialCrawl. Call estimate_cost and report the hold "
        "before any call_endpoint. If a call returns INSUFFICIENT_CREDITS, tell the user and stop."
    ),
    tools=[estimate_cost, call_endpoint],
)

Read a profile and its posts

Run the agent from the folder that holds socialcrawl_agent, and ask for the price first. The estimate is free, and its hold is the most the call can take.

Terminal
adk run socialcrawl_agent
# [user]: Quote tiktok/profile for handle=nasa, then read it and its latest videos.

Keep spend in check

Call estimate_cost before any paid call and show the answer to the person who owns the key. The instruction above makes the agent quote first, and max_credits stops a list walk 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.

Use the MCP toolset

The hosted server at https://mcp.socialcrawl.dev/mcp takes your key as a bearer header and brings its own estimate tool, so there are no functions to write. Swap the toolset in for the two functions.

socialcrawl_agent/agent.py
import os

from google.adk import Agent
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams

root_agent = Agent(
    name="socialcrawl_agent",
    model="gemini-2.5-flash",
    instruction="Use socialcrawl_estimate and report the cost before any paid call.",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mcp.socialcrawl.dev/mcp",
                headers={"Authorization": f"Bearer {os.environ['SOCIALCRAWL_API_KEY']}"},
            )
        )
    ],
)

Resources

On this page