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

# Get a TinyAgent Run as Structured JSON

> Run an agent and get the result back in an exact, predictable shape

> [!NOTE]
>
> **Capability:**`output_schema`

Use this when you need the result to land in a fixed shape every time — one
field is enough for a schema, not for assembling a whole dataset.

## Run It With a Schema

**1. Type your goal**

Write the goal as usual. Next to it, the **Schema** button is where
you'll define the shape of the result.

![Agent Playground with the goal typed and a tooltip on the Schema button explaining structured output](https://mintcdn.com/tinyfish/6Yr77veemMps6Ft4/images/agent-tutorial/structured-output/01-goal-schema-tooltip.png?fit=max\&auto=format\&n=6Yr77veemMps6Ft4\&q=85\&s=bf45034eaad14572d4840fbd5a37f483)

Click **Schema** to define the result shape instead of free text.

**2. Define the output schema**

Build the shape field by field. Here, `products` is an array of objects,
each with a `name` (string) and `price` (string — this page's prices
include a currency symbol, so a `number` field would silently drop them;
see Common Mistakes below).

![Output Schema builder with a products array field containing name and price fields](https://mintcdn.com/tinyfish/6Yr77veemMps6Ft4/images/agent-tutorial/structured-output/02-schema-builder.png?fit=max\&auto=format\&n=6Yr77veemMps6Ft4\&q=85\&s=6d94f7062b7ddd0006a8347a07ed26fa)

Add each field and its type, then click **Save**.

**3. Run it**

The goal box now shows **Schema: On**. Click **Run**.

![Agent Playground with Schema On badge next to the Run button](https://mintcdn.com/tinyfish/6Yr77veemMps6Ft4/images/agent-tutorial/structured-output/03-schema-on-run.png?fit=max\&auto=format\&n=6Yr77veemMps6Ft4\&q=85\&s=a9c991027d5f734a56b28d2b32d6cefe)

**Schema: On** confirms it's attached — then click **Run**.

**4. Watch it run live**

![Live run view showing the ScrapeMe shop page being visited](https://mintcdn.com/tinyfish/6Yr77veemMps6Ft4/images/agent-tutorial/structured-output/04-run-live.png?fit=max\&auto=format\&n=6Yr77veemMps6Ft4\&q=85\&s=dde5e86fbba77a6bcf7f64a18b4230b2)

The agent visits the page and extracts the data while you watch.

**5. Read the structured result**

The result matches the schema exactly — same field names, same types,
every time.

![Completed run result shown as JSON matching the defined schema exactly](https://mintcdn.com/tinyfish/6Yr77veemMps6Ft4/images/agent-tutorial/structured-output/05-result-json.png?fit=max\&auto=format\&n=6Yr77veemMps6Ft4\&q=85\&s=42c3fde71cebc31eb57663519711fcf3)

Raw JSON, shaped exactly like the schema.

Toggle to a table for the same data:

![Same result toggled to a readable table view](https://mintcdn.com/tinyfish/6Yr77veemMps6Ft4/images/agent-tutorial/structured-output/06-result-table.png?fit=max\&auto=format\&n=6Yr77veemMps6Ft4\&q=85\&s=c2371273e229b7c08fc72fdf5f30516a)

Same result, table view.

## Or With the API

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

client = TinyFish()

run = client.agent.run(
    url="https://scrapeme.live/shop",
    goal="Extract the first 2 product names and prices.",
    output_schema={
        "type": "object",
        "properties": {
            "products": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "price": {"type": "string"},
                    },
                    "required": ["name", "price"],
                },
            },
        },
        "required": ["products"],
    },
)

print(run.result)
```

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

const client = new TinyFish();

const run = await client.agent.run({
  url: "https://scrapeme.live/shop",
  goal: "Extract the first 2 product names and prices.",
  output_schema: {
    type: "object",
    properties: {
      products: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            price: { type: "string" },
          },
          required: ["name", "price"],
        },
      },
    },
    required: ["products"],
  },
});

console.log(run.result);
```

```bash cURL theme={null}
curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -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.",
    "output_schema": {
      "type": "object",
      "properties": {
        "products": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "price": { "type": "string" }
            },
            "required": ["name", "price"]
          }
        }
      },
      "required": ["products"]
    }
  }'
```

```json Result theme={null}
{
  "products": [
    { "name": "Bulbasaur", "price": "£63.00" },
    { "name": "Ivysaur", "price": "£87.00" }
  ]
}
```

The schema wins over the wording of the goal — if the schema describes a
single object, you get a single object even if the goal says "list all of
them." So list results always need an array field (see
[Returning a List of Items](https://docs.tinyfish.ai/agent/api/agent/structured-output.md#returning-a-list-of-items)).

## Common Mistakes

> [accordion] A field silently drops instead of erroring
>
> If a field's type can't hold what the page actually shows, the agent
> drops that item from the result instead of failing loudly. The price on
> this page renders as `£63.00` — a `number` field can't hold the currency
> symbol, so a `price: { "type": "number" }` schema returns `"products": []`
> instead of an error. Use `"type": "string"` when the source text isn't a
> bare number, as this guide now does.

> [accordion] Schema built but not turned on
>
> Building fields in the Schema panel and clicking Save does not enable
> enforcement by itself — the separate **Output Schema** toggle at the top
> of the panel must also be switched to **On**. The goal box shows
> **Schema: On** only once both steps are done; if you only did the first,
> the schema is silently ignored.

## Related

> [card] [Structured Output Reference](https://docs.tinyfish.ai/agent/api/agent/structured-output.md)
>
> Supported types, keyword allowlist, size/depth limits, common rewrites

> [card] [TinyAgent Reference](https://docs.tinyfish.ai/agent/api)
>
> Full request and response schema


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.