> ## 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.

# Form Filling

> Automate form filling and submission

## Basic Example

Fill and submit a contact form:

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

  client = TinyFish()

  with client.agent.stream(
      url="https://example.com/contact",
      goal="""Fill in the contact form:
          - Name field: "John Doe"
          - Email field: "john@example.com"
          - Message field: "I am interested in your services."
          Then click the Submit button and extract the success message.
      """,
  ) as stream:
      for event in stream:
          if event.type == EventType.COMPLETE and event.status == RunStatus.COMPLETED:
              print("Result:", event.result_json)
  ```

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

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://example.com/contact",
      goal: `Fill in the contact form:
        - Name field: "John Doe"
        - Email field: "john@example.com"
        - Message field: "I am interested in your services."
        Then click the Submit button and extract the success message.
      `,
    });

    for await (const event of stream) {
      if (event.type === EventType.COMPLETE && event.status === RunStatus.COMPLETED) {
        console.log("Result:", event.result);
      }
    }
  }

  main();
  ```

  ```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://example.com/contact",
      "goal": "Fill in the contact form with name John Doe and email john@example.com, then click Submit"
    }'
  ```

  ```bash CLI theme={null}
  tinyfish agent run "Fill in the contact form: Name: John Doe, Email: john@example.com, Message: I am interested in your services. Then click Submit and return the success message." \
    --url example.com/contact --pretty
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "success": true,
  "message": "Thank you for contacting us!"
}
```

## Multi-Step Form

Handle multi-step forms in a single goal:

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

  client = TinyFish()

  with client.agent.stream(
      url="https://example.com/signup",
      goal="""Complete the multi-step signup form:

          Step 1 (Personal Info):
          - First name: "John"
          - Last name: "Doe"
          - Email: "john@example.com"
          - Click "Next"

          Step 2 (Address):
          - Street: "123 Main St"
          - City: "San Francisco"
          - State: "CA"
          - ZIP: "94102"
          - Click "Next"

          Step 3 (Preferences):
          - Select "Email notifications" checkbox
          - Click "Submit"

          Extract the confirmation number from the success page.
      """,
  ) as stream:
      for event in stream:
          print(event)
  ```

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

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://example.com/signup",
      goal: `Complete the multi-step signup form:

        Step 1 (Personal Info):
        - First name: "John"
        - Last name: "Doe"
        - Email: "john@example.com"
        - Click "Next"

        Step 2 (Address):
        - Street: "123 Main St"
        - City: "San Francisco"
        - State: "CA"
        - ZIP: "94102"
        - Click "Next"

        Step 3 (Preferences):
        - Select "Email notifications" checkbox
        - Click "Submit"

        Extract the confirmation number from the success page.
      `,
    });

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

  main();
  ```

  ```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://example.com/signup",
      "goal": "Complete the multi-step signup form: Step 1 - First name John, Last name Doe, Email john@example.com, click Next. Step 2 - Street 123 Main St, City San Francisco, State CA, ZIP 94102, click Next. Step 3 - Select Email notifications checkbox, click Submit. Extract the confirmation number."
    }'
  ```
</CodeGroup>

## Tips

* Use stealth mode for login/signup forms
* Be explicit about field values in your goal
* Describe buttons by their text ("click 'Submit'")
* Handle multi-step forms in one goal

## Try It

<Steps>
  <Step title="Save the code">Save any example above as `form.ts`</Step>
  <Step title="Set your API key">`export TINYFISH_API_KEY="your_api_key" `</Step>
  <Step title="Run it">`npx tsx form.ts `</Step>
</Steps>

## Related

<CardGroup cols={2}>
  <Card title="Web Scraping" icon="magnifying-glass" href="/examples/scraping">
    Extract data from pages
  </Card>

  <Card title="Run SSE API" icon="code" href="/api-reference">
    Complete API docs
  </Card>
</CardGroup>