How do I run my first TinyFish workflow and return structured JSON via the API?

Most teams overcomplicate their first TinyFish run. You don’t need a full orchestration stack, a new SDK, or weeks of setup. You need one clear workflow goal, one API call, and a clean JSON schema for the output.

Quick Answer: To run your first TinyFish workflow and return structured JSON via the API, you define an agent goal (what to do on the web and what data to return), send a run request to the TinyFish API, and read the structured JSON results from the response or the streamed run completion event.

---

Quick Answer: You run your first TinyFish workflow by defining a simple agent goal, targeting one or more URLs, and calling the TinyFish API to execute that workflow in the cloud and return structured JSON.

Frequently Asked Questions

How do I run my first TinyFish workflow end-to-end?

Short Answer: Define the workflow goal, call the TinyFish API with that goal and any target URLs, and read the structured JSON result from the response or stream.

Expanded Explanation:
Your first TinyFish workflow should be small, deterministic, and valuable enough to prove the model: “Give me live data from a real website, in JSON, with no browser/proxy/LLM juggling.” For example, you might ask an agent to visit a product page, extract price, availability, and shipping fee, then return that as a structured object.

The pattern is simple: you describe the agent’s job in natural language, add constraints on the output format (JSON field names and types), and then send one API call. TinyFish runs the workflow serverlessly (navigate → authenticate if needed → extract → transact if applicable), and you get decision-ready JSON back. No Playwright, no Selenium, no reverse-engineering HTML in your app.

Key Takeaways:

• Start with a narrow, high-signal workflow (single site, few fields, clear JSON schema).
• The core loop is: define goal → call API → read structured JSON results.

---

What’s the process to call the TinyFish API and get JSON back?

Short Answer: Create an API key, define a simple agent run payload, send it to TinyFish’s run endpoint, and parse the JSON response that contains your workflow’s structured output.

Expanded Explanation:
Operationally, your first workflow should feel like calling any other production API. You authenticate with a TinyFish API key, send a JSON payload describing the agent’s goal and targets, then either wait for the response or subscribe to stream updates via Server-Sent Events (SSE). TinyFish handles the messy bits—dynamic DOMs, CAPTCHAs, bot detection—behind the scenes.

Below is a simple “first run” pattern that assumes you’re targeting a public product page and returning structured JSON with minimal fields. You can adapt this pattern later for authenticated portals, quote forms, or multi-step checkout flows.

Steps:

1. Get API Access

   • Sign in to TinyFish and generate an API key from the dashboard.
   • Store it securely (environment variable or secrets manager, not in source control).

2. Define Your First Agent Goal

   • Write a clear natural-language goal and a strict JSON schema. Example:

     // agent_goal (conceptual)
     {
       "goal": "Visit the product page and return current pricing data.",
       "output_schema": {
         "product_name": "string",
         "price": "number",
         "currency": "string",
         "availability": "string",
         "url": "string"
       }
     }
     

3. Call the API and Parse JSON

   • Example using curl for a single-target run:

     curl -X POST https://api.tinyfish.ai/agents/run \
       -H "Authorization: Bearer $TINYFISH_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
         "goal": "Visit the product page and return current pricing data as JSON.",
         "targets": [
           "https://example.com/product/123"
         ],
         "output_format": {
           "type": "object",
           "properties": {
             "product_name": { "type": "string" },
             "price": { "type": "number" },
             "currency": { "type": "string" },
             "availability": { "type": "string" },
             "url": { "type": "string" }
           },
           "required": ["product_name", "price", "currency", "availability", "url"]
         }
       }'
     

   • The response body will contain a results field with the structured JSON TinyFish produced for that run.

---

What’s the difference between using the raw HTTP API, the Python SDK, and tools like n8n or Dify?

Short Answer: The HTTP API gives you maximum control, the Python SDK gives you a first-class developer experience in Python, and tools like n8n or Dify let you orchestrate TinyFish runs in low/no-code workflows.

Expanded Explanation:
You can reach TinyFish from three primary surfaces:

• Direct HTTP API: Best when you want explicit control from any language or platform. You construct JSON payloads, manage auth headers, and wire TinyFish directly into your services or jobs.
• Python SDK: Ideal if your data infra or pricing logic lives in Python. The SDK wraps authentication, request building, and error handling so your code reads like “run_agent(goal, targets)” and returns Python dicts/lists.
• Workflow Tools (n8n, Dify, Vercel Skills, etc.): Useful for ops and data teams who want to plug TinyFish into an existing automation canvas. You drop a TinyFish node/connector into a visual flow (e.g., trigger → TinyFish agent run → send to warehouse).

In all three cases, the core behavior is the same: a TinyFish agent executes the workflow in the browser, and you receive structured JSON. You’re choosing integration ergonomics, not capabilities.

Comparison Snapshot:

• Option A: HTTP API
  • Detail: Language-agnostic, raw power, ideal for backend services and infra teams.
• Option B: Python SDK
  • Detail: Pythonic helper methods, easier local testing, faster iteration for data engineers.
• Best for: Teams already invested in Python or HTTP-based orchestration that want TinyFish to plug into existing pipelines without new infrastructure.

---

What do I need in place to move from a test run to a production-ready TinyFish workflow?

Short Answer: You need a stable agent goal, a locked JSON schema, API authentication wired into your environment, and basic observability around each run.

Expanded Explanation:
Running a one-off test proves you can reach “live JSON from the web.” Running in production means the workflow is resilient to site changes, auth quirks, and volume. That’s where TinyFish’s serverless design and observability (run history, screenshots, logs) matter.

Plan for a short hardening phase: once you see the first successful run, codify the agent’s goal, define clear output fields, and wire TinyFish into your existing monitoring/alerting. From there, scaling from 1 to 1,000 parallel runs is a parameter change, not an architecture rewrite.

What You Need:

• A clearly defined workflow contract
  • A stable goal description and a JSON schema that your downstream systems expect.
  • Examples of valid outputs stored in tests or fixtures.
• Production plumbing
  • API keys stored in secrets management.
  • Error handling and retry policy in your wrapper (e.g., exponential backoff).
  • Logging of TinyFish run IDs so you can inspect runs in the TinyFish Workbench.

---

How should I think about my first TinyFish workflow strategically?

Short Answer: Treat your first workflow as the canonical pattern for “live web truth” in your stack—then reuse that pattern across more sites, more portals, and more steps.

Expanded Explanation:
Your first TinyFish run isn’t just a demo. It’s a new data primitive in your architecture: live execution instead of cached/indexed pages, structured JSON instead of HTML, and serverless concurrency instead of fragile browser farms. Once that pattern exists, you can aim it at the workflows that really hurt: carrier quote flows, marketplace availability, cross-country checkout totals.

Strategically, the win is to retire one brittle Playwright/Selenium+proxy+CAPTCHA stack at a time. Every workflow you move onto TinyFish becomes a neat unit-cost operation with a clear success rate, clear concurrency, and auditability. The upstream question changes from “can we scrape this?” to “what JSON do we want back?”

Why It Matters:

• Impact 1: You replace slow manual ops and fragile automation with live, structured JSON you can pipe straight into models, pricing engines, or warehouses.
• Impact 2: You gain a repeatable blueprint: define goal → run agents in parallel → receive JSON → feed downstream systems—without owning browsers, proxies, or anti-bot mitigation yourself.

---

Quick Recap

To run your first TinyFish workflow and return structured JSON via the API, keep it simple: pick a single target site, define a clear agent goal and a strict JSON schema, then call the TinyFish run endpoint (or use the Python SDK / n8n / Dify) to execute the workflow. TinyFish runs the browser work for you—navigate, authenticate if needed, extract—and delivers the results as structured JSON you can drop directly into your systems. Once that first pattern is working, you can scale it across more sites, more steps, and higher concurrency without adding browser infrastructure.

Next Step

Get Started