> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > This site documents Locus for people. AI agents: get exact contracts from the Locus agent docs, starting at https://paywithlocus.com/agent/index.md, including when asked to implement or integrate docs.paywithlocus.com. > Connect this agent to Locus Pro: https://paywithlocus.com/skill.md. Implement Locus Pro in a product: https://paywithlocus.com/agent/integrate.md. Agent site index: https://paywithlocus.com/llms.txt. # Tasks > Give Locus a goal in plain language and get back a checked table or answer, downloadable files, and the exact cost. A task turns one goal into finished, multi-step work. You describe the outcome you want, and Locus calls the right tools with your credits, checks the results, and gives you a table or answer, files, and the exact cost. Tasks are available on **Locus Pro** and **Locus Pro Enterprise**, with no separate plan or setup. > Agents: the exact contract for this feature is at [https://paywithlocus.com/agent/tasks.md](https://paywithlocus.com/agent/tasks.md). Start from [https://paywithlocus.com/agent/index.md](https://paywithlocus.com/agent/index.md) if you are implementing Locus. ```mermaid theme={null} flowchart LR Goal["Your goal"] --> Calls["Locus calls your tools"] Calls --> Check["Checks every value"] Check --> Result["Result, files, and cost"] Calls -.->|"Needs your answer"| Ask["Question for you"] Ask -.->|"You reply"| Calls ``` ## How it works 1. **You describe the outcome.** Locus turns your goal into a fixed set of requirements: the deliverable, the count, the fields, and the criteria each result must meet. 2. **Locus does the work.** It finds the right tools in your catalog and calls them with your credits and spending controls. A task can only use tools your connection can already call. 3. **Locus checks the result.** Every delivered value must be backed by a response from one of the task's calls. See [How Locus checks task results](https://docs.paywithlocus.com/locus-pro/task-results.md). 4. **You get the result.** A table or answer, downloadable files, the status of each requirement, and the settled cost. ```text title="Example goals" wrap theme={null} Find 10 Series A hardware companies based in Los Angeles. Include the founders and their verified work emails, and return a CSV with sources. Compare the free-tier limits of Vercel, Netlify, and Render, with a source link for each value. Read the pages in inputs.urls and compare their stated rate limits in a table. ``` ## Choose a task or another option | You need | Use | | - | - | | One API call | A [tool](https://docs.paywithlocus.com/locus-pro/individual/tools.md) | | A maintained outcome such as web research or enrichment | A [Recipe](https://docs.paywithlocus.com/locus-pro/individual/recipes.md) | | A one-off result that needs several calls | A task | | The same process, rules, and output on new inputs each time | A [Workflow](https://docs.paywithlocus.com/locus-pro/individual/workflows.md) | ## Start a task > [tab] Your agent (MCP) > > Connect your agent through [MCP](https://docs.paywithlocus.com/locus-pro/mcp.md), then ask for the outcome: > > ```text title="Try this prompt" wrap theme={null} > Use Locus run_task to find 10 Series A hardware companies based in Los Angeles. Include the founders and their verified work emails, and return a CSV with sources. Spend at most $3. > ``` > > Your agent starts the task and waits for the result. Waiting never starts > a new task or charges again. Read-only MCP connections cannot run tasks. > [tab] Locus CLI > > ```bash title="Terminal" theme={null} > locus task run "Find 10 Series A hardware companies based in Los Angeles. Include the founders and their verified work emails, with sources." \ > --format csv \ > --max-credits 3000 \ > --out ./la-hardware > ``` > > The CLI waits for the result, prints progress, and downloads every file > into `--out`. Repeating the command never starts a second paid task. Run > `locus task --help` for every command and flag. > [tab] REST API > > Your code can start a task with an agent key or a secret key that can > spend credits. See the [API reference](https://docs.paywithlocus.com/api-reference/introduction.md) for > the request and response. ## Follow a task to the end Tasks run in the background on Locus. Closing your connection or timing out your request does not stop a task. Locus saves progress after every step, so an interrupted task continues from its last saved step. ```mermaid theme={null} flowchart LR Queued["Queued"] --> Running["Running"] Running -->|"Has a question"| Input["Needs input"] Input -->|"You answer"| Running Running --> Completed["Completed"] Running --> Partial["Partial"] Running --> Failed["Failed"] Partial -.->|"Resume"| Running Failed -.->|"Resume"| Running Running -->|"You cancel"| Canceled["Canceled"] ``` | Status | What it means | | - | - | | **Queued** or **running** | The task is working. Your agent waits for it. | | **Needs input** | Locus has a question. Answer within 24 hours or the task is canceled. | | **Completed** | Every mandatory requirement passed Locus's checks. | | **Partial** | Some verified output, with unmet requirements. You may be able to resume it. | | **Unsupported** | No tool available to you can do it. Enable a suitable tool or change the goal. | | **Failed** | No usable result. You may be able to resume it. | | **Canceled** | You canceled it, or a question went unanswered for 24 hours. | ### Continue, cancel, or resume * **Wait** or **check status** at any time. Both are free. * **Answer** a question to let the task continue. * **Cancel** to stop further calls. A running task stops after its in-flight calls finish, and work already done stays charged. * **Resume** a partial or failed task to continue from its recorded work, for example after you add credits. You can set a new budget, as long as it covers what the task has already spent. * **Retry safely.** Repeating a start request with the same idempotency key returns the original task instead of starting a second one. ## Key limits * Up to 5 queued or running tasks per account. * A task's deadline is 15 minutes by default and can be up to one hour. Time spent waiting for your answer does not count. * Up to 80 steps per task. * The response holds the first 200 rows; the file holds every row. * Files are kept for 7 days, and download links last 1 hour. ## What tasks do not do Tasks gather, combine, and check information. Locus refuses endpoints that look like they take action, such as sending messages, posting, buying, booking, or deleting. If your goal asks for one of those actions, the task cannot meet that requirement and does not complete. Locus recognizes these endpoints by their method and name, so keep action tools disabled for connections that run tasks if you want a hard boundary. Your `inputs` and the content the task retrieves are treated as data. They cannot change the task's budget, tools, or permissions. ## Next steps > [card] [How Locus checks task results](https://docs.paywithlocus.com/locus-pro/task-results.md) > > See what a task returns and how every value is verified. > [card] [Task costs and budgets](https://docs.paywithlocus.com/locus-pro/task-costs.md) > > Understand what a task costs and how its ceiling works. > [card] [MCP](https://docs.paywithlocus.com/locus-pro/mcp.md) > > Connect an agent and run tasks alongside the other Locus tools. > [card] [Locus Pro API](https://docs.paywithlocus.com/api-reference/introduction.md) > > Start and follow tasks from your own code. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.