> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API

> Use natural-language goals to automate workflows on real websites

The TinyFish Agent API lets you describe a task in natural language and have TinyFish execute it on a real website. Use it when you want goal-based automation rather than low-level browser scripting.

<Note>
  The Agent API is the right choice when TinyFish should decide the browser actions. If you need direct browser control instead, use the [Browser API](/browser-api).
</Note>

## Canonical Endpoints

| Endpoint     | Pattern           | Best for                               |
| ------------ | ----------------- | -------------------------------------- |
| `/run`       | Synchronous       | Quick tasks and simple integrations    |
| `/run-async` | Start then poll   | Long tasks and batch processing        |
| `/run-sse`   | Live event stream | Real-time progress in user-facing apps |

```bash theme={null}
POST https://agent.tinyfish.ai/v1/automation/run-sse
```

## Before You Start

<Steps>
  <Step title="Get your API key">
    Create an API key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
  </Step>

  <Step title="Store it in your environment">
    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for the full setup and troubleshooting guide.

## Your First Request

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  with client.agent.stream(
      url="https://scrapeme.live/shop",
      goal="Extract the first 2 product names and prices. Return JSON.",
  ) as stream:
      for event in stream:
          print(event)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  const stream = await client.agent.stream({
    url: "https://scrapeme.live/shop",
    goal: "Extract the first 2 product names and prices. Return JSON.",
  });

  for await (const event of stream) {
    console.log(event);
  }
  ```

  ```bash cURL theme={null}
  curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://scrapeme.live/shop",
      "goal": "Extract the first 2 product names and prices. Return JSON."
    }'
  ```
</CodeGroup>

## What Success Looks Like

```json theme={null}
{"type":"STARTED","run_id":"abc123"}
{"type":"PROGRESS","run_id":"abc123","purpose":"Visit the page to extract product information"}
{"type":"PROGRESS","run_id":"abc123","purpose":"Extract the first two products and prices"}
{"type":"COMPLETE","run_id":"abc123","status":"COMPLETED","result":{"products":[{"name":"Bulbasaur","price":"£63.00"},{"name":"Ivysaur","price":"£87.00"}]}}
```

The agent's answer comes back in `result`: a JSON object appears directly (as above), while a bare list or plain-text answer arrives under `result.result`. Pass an [`output_schema`](/key-concepts/structured-output) for guaranteed typed fields.

If you want a blocking request that returns only the final result, use `/run`. If you want to start work and poll later, use `/run-async`.

## When to Use Agent vs the Other APIs

* Use **Agent** when TinyFish should decide the browser actions from your goal.
* Use **Browser** when you want to drive Playwright or CDP yourself.
* Use **Fetch** when you already know the URLs and only need extracted page content.
* Use **Search** when you need ranked search results rather than page automation.

## Writing Good Goals

A goal is the plain-English instruction you pass in the `goal` field. TinyFish uses it to decide what to click, type, extract, and return.

Good goals are:

* specific about the output you want
* explicit about the page or flow to follow
* clear about response format when you need structured JSON

## Read Next

<CardGroup cols={2}>
  <Card title="Agent reference" icon="code" href="/agent-api/reference">
    Full request schema, run lifecycle, browser profiles, and errors
  </Card>

  <Card title="Structured Output" icon="code" href="/key-concepts/structured-output">
    Schema support, limits, and examples
  </Card>

  <Card title="Endpoint selection" icon="plug" href="/key-concepts/endpoints">
    Choose between `/run`, `/run-async`, and `/run-sse`
  </Card>

  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Understand status, polling, and completion
  </Card>

  <Card title="Goal prompting guide" icon="bullseye" href="/prompting-guide">
    Write more reliable automation instructions
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>
</CardGroup>