# AI agents and apps (/docs/use-cases/ai-agents) Give an agent public social data through one key and the SocialCrawl MCP tools. An agent on SocialCrawl needs one API key and a way to ask for calls. It plans the calls a job needs, prices them for free, then runs them under a cap you set. Every failure comes back with a type the agent can act on. ## Start with a template - [Set up your agent](/docs/quickstart/agents.md): One prompt that connects your agent to SocialCrawl and makes its first call. - [Templates](/docs/templates.md): Tested programs an agent can read and run, also listed by GET /v1/utility/recipes. ## Run your first request This request asks the planner which calls a job needs. It costs nothing and runs nothing. **cURL** ```bash title="cURL" curl -G "https://www.socialcrawl.dev/v1/utility/plan" \ --data-urlencode "query=Combine @acme's TikTok profile with their recent videos and the comments on them" \ -H "x-api-key: sc_your_key_here" ``` **Python** ```python title="Python" import json import urllib.parse import urllib.request params = urllib.parse.urlencode({ "query": "Combine @acme's TikTok profile with their recent videos and the comments on them", }) url = "https://www.socialcrawl.dev/v1/utility/plan" req = urllib.request.Request( url + "?" + params, headers={"x-api-key": "sc_your_key_here"}, ) with urllib.request.urlopen(req) as res: plan = json.load(res)["data"] for step in plan["steps"]: print(step["path"], step["credits"], step["run"]) ``` **TypeScript** ```typescript title="TypeScript" const url = new URL("https://www.socialcrawl.dev/v1/utility/plan"); url.searchParams.set("query", "Combine @acme's TikTok profile with their recent videos and the comments on them"); const res = await fetch(url, { headers: { "x-api-key": "sc_your_key_here" }, }); const { data } = await res.json(); for (const step of data.steps) { console.log(step.path, step.credits, step.run); } ``` The answer is a list of `steps`: the profile, then its videos, then the comments on each video. Each step carries its path, its price in credits, the values still missing and a ready cURL. A step marked `blocked` waits on a value from the step before it. [Endpoint pricing](/docs/endpoint-pricing.md) lists the price of every call. Before it runs a plan, the agent can price all of it with `socialcrawl_estimate`, which takes one call, a plan of several calls or a walk of a number of rows. To gather many rows, `socialcrawl_collect` walks the pages, supplies the cursors and drops duplicates. It stops at the rows you asked for, at the last page or at `max_credits`, and its `result_id` reads the stored result again for free. `socialcrawl_account` reads the balance and this session's spend for free, so the agent can tell you what a job cost. ## How it works 1. **Connect** the agent with the [agent quickstart](/docs/quickstart/agents.md), or register the [MCP server](/docs/skills-and-mcp.md) with your client. 2. **Plan** the job: the agent asks `socialcrawl_find` or [`GET /v1/utility/plan`](/docs/utility.md) for the calls and their prices. 3. **Run** the calls with a `max_credits` cap and read the answer. ## Why teams choose SocialCrawl **Discovery is free and needs no key.** The three discovery tools of the MCP server, `socialcrawl_find`, `socialcrawl_endpoint` and `socialcrawl_estimate`, [cost nothing](/docs/skills-and-mcp.md#available-tools). **The agent cannot pass your cap.** `socialcrawl_request` refuses a call above `max_credits`, so no single call costs more than you allowed. **Errors say what to do next.** Every failure carries an `error.type` to branch on and a `doc_url` that points at its entry in [Error handling](/docs/errors.md). ## Related - [Market research](/docs/use-cases/market-research.md): Read what people say about a topic across platforms. - [Influencer marketing](/docs/use-cases/influencer-marketing.md): Find creators in a market and follow their new posts. - [SocialCrawl for AI agents](/solutions/ai-agents): How teams build agents and apps on SocialCrawl.