For complete endpoint specifications, see the AgentTools API reference.

Learn how to find a supported template, create a cloud extraction task, monitor its progress, and export the results with the Octoparse AgentTools API.

The AgentTools API is designed for AI agents and automated workflows that need to turn a data-collection request into an executable Octoparse cloud task.

Instead of manually creating and configuring a task through low-level APIs, the AgentTools API guides your workflow through template discovery, parameter validation, task execution, and data export.

Before you start

You need:

An Octoparse API key
An external user ID for task creation and task search
Access to a supported cloud-executable template

Use the following base URL:

https://openapi.octoparse.com

For AgentTools requests, send your API key in the request header:

x-api-key: YOUR_API_KEY

The executeTask and searchTasks endpoints also require:

x-external-user-id: YOUR_EXTERNAL_USER_ID

Workflow overview

For a new scraping request, use this sequence:

searchTemplates
→ executeTask
→ exportData

For an existing Octoparse task, use:

searchTasks
→ startOrStopTask
→ exportData

Do not call executeTask before you know which template to use and which parameters it requires.

Example: collect Amazon product listings

This example searches for a supported Amazon product template, creates a task for wireless earbuds, then waits for the export file.

Step 1: Search for a template

Use searchTemplates to find a template that matches the website and data you want to collect.

curl -sS \
  "https://openapi.octoparse.com/api/agentTools/searchTemplates?keyword=amazon%20product&page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

The response includes a template list and may include a recommended template name.

Look for:

recommendedTemplateName
templates[].slug
templates[].executionMode
templates[].inputSchema
templates[].sourceTree
templates[].outputSchema

Use a cloud-executable template. A local-only template cannot be started through executeTask.

Step 2: Read the input schema

Before creating a task, inspect the selected template’s inputSchema.

Each field describes a parameter accepted by the template. Use inputSchema[].field as the parameter key when building your request.

For example, a template may require:

{
  "search_keyword": ["wireless earbuds"],
  "site": "US"
}

Important rules:

parameters must be sent as a JSON object serialized into a string.
Use inputSchema[].field as the parameter key.
For multi-value fields, send an array even when there is only one value.
For source-backed fields, send the option key, not the displayed label.
If a field depends on another field, select the parent option first.

Step 3: Create and start the cloud task

Call executeTask with the selected template and parameters.

curl -sS -X POST \
  "https://openapi.octoparse.com/api/agentTools/executeTask" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-external-user-id: YOUR_EXTERNAL_USER_ID" \
  -d '{
    "templateName": "amazon_product_search",
    "taskName": "Amazon wireless earbuds",
    "parameters": "{\"search_keyword\":[\"wireless earbuds\"],\"site\":\"US\"}",
    "targetMaxRows": 100
  }'

A successful response returns a task ID and usually has this status:

{
  "data": {
    "success": true,
    "status": "accepted",
    "taskId": "task_abc",
    "retryGuidance": {
      "tool": "export_data",
      "waitSecondsMin": 60
    }
  }
}

accepted means Octoparse has created the task and requested that cloud extraction start. It does not mean the export file is ready.

Save the returned taskId. You will use it in the next step.

Step 4: Handle validation and source-selection issues

If executeTask returns status: "invalid", inspect the response before retrying.

Common fields include:

missingParamNames
blockingIssues
invalidSourceSelections
inputSchema
recoverySuggestion

For example, if the response says that site is required, add it to your parameters and call executeTask again.

If the response returns:

awaiting_source_selection

the template needs an additional source-backed value. Query the template again by ID or slug, inspect sourceTree, choose the correct option key, then retry the request.

Do not retry indefinitely when requiresUserAction is true.

Step 5: Poll for export progress

After executeTask returns accepted, wait for the duration specified in retryGuidance.

Then call exportData:

curl -sS \
  "https://openapi.octoparse.com/api/agentTools/exportData?taskId=task_abc&exportFileType=JSON&previewRows=5" \
  -H "x-api-key: YOUR_API_KEY"

The API may return one of these statuses:

Status	Meaning	What to do
`collecting`	The task is still running.	Wait for the recommended interval and retry.
`exporting`	The export file is being generated.	Wait for the recommended interval and retry.
`exported`	The file is ready.	Show the export URL and preview data.
`no_data`	The task completed but returned no rows.	Review the template, parameters, or target site.
`failed`	The task or export failed.	Check `error`, `recoverable`, and `retryGuidance`.
`invalid`	The request is invalid.	Check `taskId`, export type, and preview row count.

Always follow the returned retryGuidance, suggestedNextCall, or workflow fields when present. Do not hard-code a polling interval unless your integration has no guidance from the API.

Step 6: Use the exported data

When the export is ready, the response looks similar to this:

{
  "data": {
    "success": true,
    "status": "exported",
    "taskId": "task_abc",
    "exportFileType": "JSON",
    "dataTotal": 100,
    "exportFileUrl": "https://...",
    "sampleData": [
      {
        "title": "Product A",
        "price": "$19.99"
      }
    ]
  }
}

When status is exported:

Show the user the exportFileUrl.
Display sampleData as a preview when available.
Use dataTotal to report how many rows were collected.

Do not automatically download or parse exportFileUrl unless your user explicitly asks to inspect or analyze the exported file.

Manage an existing task

Use this workflow when the task already exists:

searchTasks
→ startOrStopTask
→ exportData

Find a task

curl -sS \
  "https://openapi.octoparse.com/api/agentTools/searchTasks?page=1&size=10&keyword=amazon" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-external-user-id: YOUR_EXTERNAL_USER_ID"

The response includes task IDs, task names, and task statuses.

Start or stop a task

To start a task:

curl -sS -X POST \
  "https://openapi.octoparse.com/api/agentTools/startOrStopTask" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "taskId": "task_abc",
    "action": "start"
  }'

To stop a task, change the action to:

{
  "taskId": "task_abc",
  "action": "stop"
}

Possible response statuses include:

start_requested
stop_requested
already_running
already_stopped
start_rejected
stop_rejected
invalid

After a successful start request, use exportData to monitor collection and export progress.

Common implementation mistakes

Sending `parameters` as an object

Incorrect:

{
  "parameters": {
    "search_keyword": ["wireless earbuds"]
  }
}

Correct:

{
  "parameters": "{\"search_keyword\":[\"wireless earbuds\"]}"
}

Treating `accepted` as completion

accepted only confirms that task creation and the cloud-start request were accepted. Continue with exportData until the status becomes exported.

Passing labels instead of source option keys

For source-backed template fields, use the option key returned by sourceTree, not the user-facing label.

Ignoring retry guidance

When the API returns retryGuidance, suggestedNextCall, or workflow, use those fields to determine the next call and waiting period.

Next steps

For complete request and response schemas, see:

Lesson 0: Octoparse Basics

What is a task in Octoparse

How to Connect Octoparse with Zapier

Octoparse API FAQs

Connect to Octoparse APIs with Postman

Run a scraping workflow with the Octoparse AgentTools API