# Utility Call Planner API (https://www.socialcrawl.dev/platforms/utility/plan)

> Turn a job written in plain words ("track mentions of Acme on TikTok and Reddit", "a creator's profile, posts and comments") into the exact calls to make, in order: method, path, the parameters your question filled, the ones still missing, which step's rows fill a later step, the credit price of each call, and a curl for each with every unknown value left as a {placeholder}. Jobs are planned from the task-recipe catalog (GET /v1/utility/recipes: comment exports, creator vetting, review comparisons, monitors, crawls and more) plus brand monitoring, one creator, a topic search, a saved search on a monitor, and one GET /v1/prism/discover run for a brand's reaction, the accounts behind a topic, trends, communities, or names to their own accounts; a one-call question returns that one call, and a job that combines several sources no recipe covers is planned as a chain (one call per source, a monitor per call when it repeats). A request to act on an account (post, reply, like, follow, delete) or about billing returns no steps. Every plan carries total: the whole job's credits (paging and per-row fan-out included, for the recipe's stated size) from the same pricing the API bills with. A question outside those returns uncertain with no steps instead of a guessed chain, and anything the API cannot return (a follower history, a new-post webhook) is listed under cannot. A search value that names no topic (a placeholder such as "keyword", a country name, an English phrase for a Korean or Chinese platform, or most of the sentence) is left out and asked for under missing, with a note saying why. A job that lists several topics plans each search step once per topic and names them under topics; one that names several markets is uncertain and lists them as ISO codes under markets. Beta: recipe matches are reliable; confirm a single-endpoint or multi-source plan with utility/find. Nothing is run. Free to call.

TL;DR: `GET /v1/utility/plan` costs Free (0 credits) and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | no | The job in plain words, in any language. Up to 600 characters are read. Provide this or task |
| `task` | no | Alias for query (utility/find's name). Provide this or query |

## Code example

```bash
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_API_KEY"
```

## FAQ

### What does the Call Planner API return?

Returns the calls for a job you describe in plain words, in order: each path, the parameters your words filled, the ones still missing, its price, and a curl with unknown values left as placeholders. The response uses the same JSON envelope as every SocialCrawl endpoint, with the data, credits_used and request_id fields.

### When should I use the Call Planner endpoint?

Use it before writing an integration, when you know the job but not the endpoints. It plans and never runs anything. Free to call.

### How much does the Call Planner API cost?

This endpoint is free to call and uses no credits. Every new account still gets 100 free credits for the paid endpoints. Credits for failed or empty calls are refunded automatically, and there is no subscription.

### What parameters does the Call Planner API need?

Identify the target with one of query, task. It also accepts 2 optional parameters, all listed on this page.

### How do I call the Call Planner API?

Send a GET request to https://www.socialcrawl.dev/v1/utility/plan?query=Combine%20%40acme's%20TikTok%20profile%20with%20their%20recent%20videos%20and%20the%20comments%20on%20them with your API key in the x-api-key header. An Authorization: Bearer header works too.

See the full Utility API: https://www.socialcrawl.dev/platforms/utility

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- What does the SocialCrawl Call Planner API return?
- How do I get Call Planner data with the SocialCrawl API?