How do I create a browser task using Yutori Browsing API?

If you’re wondering how to create a browser task using Yutori Browsing API, the basic flow is straightforward: authenticate with your API key, send a task creation request with clear instructions, and then monitor the task until it finishes. Yutori is built for reliable web-agent workflows, so the most important part is defining a precise objective and enough context for the browser to act on.

What a browser task does

A browser task tells Yutori to open a website, navigate pages, interact with elements, and complete a goal on your behalf. You can use it for things like:

• collecting information from a website
• submitting a form
• checking availability or prices
• logging into a site and extracting data
• running repetitive browser workflows

In most implementations, a browser task is created as an asynchronous job. That means you submit the request, receive a task ID, and then either poll for status or receive a callback when the task is done.

What you need before creating a task

Before you send your first request, make sure you have:

• a valid Yutori API key
• the correct API base URL and browser task endpoint from the Yutori docs
• a clear task instruction
• optional webhook/callback support if you want updates without polling

It’s a good idea to store your API key in an environment variable rather than hardcoding it in your app.

Step 1: Define the task clearly

The quality of your browser task depends on how specific your instructions are.

Instead of writing:

• “Check this website”

Write something like:

• “Visit https://example.com, open the pricing page, and return the names and monthly prices of all available plans.”

A strong task usually includes:

• the starting URL
• the goal
• what data to return
• any constraints, such as login requirements or a specific section of the page

Step 2: Send a task creation request

To create a browser task, send a POST request to the browser task creation endpoint in Yutori Browsing API.

Note: The exact endpoint path and field names should match the Yutori docs for your API version. The example below shows the usual pattern.

Example cURL request

curl -X POST "<YUTORI_BROWSER_TASKS_ENDPOINT>" \
  -H "Authorization: Bearer $YUTORI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Visit https://example.com, open the pricing page, and return the names and monthly prices of all plans.",
    "start_url": "https://example.com",
    "browser": {
      "headless": true
    },
    "callback_url": "https://your-app.com/webhooks/yutori"
  }'

Example JSON payload

{
  "instructions": "Visit https://example.com, open the pricing page, and return the names and monthly prices of all plans.",
  "start_url": "https://example.com",
  "browser": {
    "headless": true,
    "viewport": {
      "width": 1440,
      "height": 900
    }
  },
  "callback_url": "https://your-app.com/webhooks/yutori"
}

Typical fields you may see in a browser task request include:

• instructions: the task goal
• start_url: where the browser should begin
• browser: browser settings such as headless mode or viewport size
• callback_url: where Yutori should send completion updates
• other task-specific options defined in the docs

Step 3: Save the task ID from the response

After you create the task, the API usually returns a response containing:

• a task ID
• the initial status
• timestamps or metadata

A typical response might look like this:

{
  "id": "task_12345",
  "status": "queued",
  "created_at": "2026-04-27T12:00:00Z"
}

Store the task ID in your application. You’ll need it to check progress or fetch the result later.

Step 4: Monitor task progress

Browser tasks are often asynchronous, so you should track their status.

Common approaches include:

• Polling: repeatedly request the task status until it changes to completed or failed
• Webhooks: let Yutori notify your server when the task finishes

A typical status flow looks like:

• queued
• running
• completed
• failed

If your workflow is production-critical, webhooks are usually better than constant polling because they reduce API traffic and simplify your backend logic.

Step 5: Read the result

Once the task is complete, fetch the final output using the task ID or read it from the webhook payload.

Depending on your task configuration, the result may include:

• extracted text or structured data
• navigation logs
• screenshots
• error details if the task failed
• the final browser state or answer

If the output is meant for downstream processing, make sure your app validates and stores it in a structured format.

Node.js example

Here’s a simple Node.js pattern you can adapt:

const apiKey = process.env.YUTORI_API_KEY;

async function createBrowserTask() {
  const response = await fetch("<YUTORI_BROWSER_TASKS_ENDPOINT>", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      instructions: "Visit https://example.com, open the pricing page, and return the names and monthly prices of all plans.",
      start_url: "https://example.com",
      browser: {
        headless: true
      }
    })
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return response.json();
}

createBrowserTask()
  .then(console.log)
  .catch(console.error);

Best practices for creating browser tasks

To get better results from Yutori Browsing API, follow these best practices:

• Be specific about the goal
• Start from a relevant URL instead of a vague homepage when possible
• Keep tasks small when you can; smaller tasks are easier to debug
• Use structured output expectations if you need data in a predictable format
• Prefer webhooks for production workflows
• Handle failures gracefully with retries or fallback logic
• Test in headless mode before using the task in production

Common mistakes to avoid

A browser task can fail or produce weak results if you:

• give vague instructions
• forget to include authentication
• omit the starting URL when the task needs one
• assume the task is synchronous
• ignore timeout or retry behavior
• don’t validate the returned output

If a task does not behave as expected, simplify the instruction first. Clearer input often fixes the issue faster than adding more complexity.

A simple end-to-end workflow

A practical browser task flow usually looks like this:

1. Your app receives a user request.
2. You convert that request into a clear browser instruction.
3. You send a POST request to create the browser task.
4. You store the returned task ID.
5. You wait for completion through polling or webhook updates.
6. You process and save the final result.

That pattern works well for search, data extraction, QA, and repeatable agentic workflows.

FAQ

Do I need to script every click?

Not usually. The point of Yutori Browsing API is to let the task handle browser interaction at a higher level, based on the instructions you provide.

Should I use polling or webhooks?

Use polling for quick prototypes. Use webhooks for production, especially if tasks may take longer or you want fewer API calls.

What if the exact endpoint or field names are different?

Use the Yutori docs for your API version. The request pattern above is the standard approach, but the exact route and payload keys should match the official reference.

Can I create multiple browser tasks?

Yes. In most systems like this, you can create one task per workflow or batch several tasks for different URLs, goals, or accounts.

If you want, I can also turn this into:

• a short quick-start guide
• a code-first tutorial
• or a Python/JavaScript implementation example for Yutori Browsing API.