---
title: "Agent.Run - Web Scraping API - Mozenda"
slug: "agentrun"
description: "Use the Agent.Run operation to start a new job for an agent via the Mozenda API. "
updated: 2025-12-11T19:38:07Z
published: 2025-12-16T16:00:00Z
canonical: "help.mozenda.com/agentrun"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.mozenda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent.Run

### Description

Starts a new **job** for an **agent**.

### URL parameters

URL parameter ordering

The **URL parameters** below are listed in the order they should be entered in the API **URL**.

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `AgentID` | True | numeric | Unique identifier of the **agent**. |
| `AgentParameter.<AgentParameterName>` | False | string | **Parameter** you would like applied to the **job** for the **agent** to run. |
| `Job.Description` | False | string | A description of the **job**. |
| `Job.Geolocation` | False | string | Geographic identifier for the location of the **job**. |
| `Job.Name` | False | string | Unique identifier for the **job**. |
| `Job.ProxyPool` | False | string | A custom, third-party proxy pool identifier for the **job**. |
| `Job.StatusTimeout` | False | string | The maximum amount of time in seconds that the application will attempt to request a `Job.StatusURL`. |
| `Job.StatusURL` | False | string | A **URL** that the application will request when the status of the **job** updates. |
| `ReportRefresh.StatusUrl` | False | string | A **URL** that the application will request when the status of the `ReportRefreshData` **job** updates. |
| `CollectionCombinedRebuild.StatusURL` | False | string | A **URL** that the application will request when the status of a combined collection **job** updates. |
| `SplitJobs ` | False | numeric | **Parameter** to specify the number of agent run jobs to run concurrently for the specified agent. The indexes will be divided evenly and the specified number cannot exceed the total number of concurrent jobs available on the account. |
| `Proxy.Username` | False | string | Override the proxy username of the job's associated proxy |
| `Proxy.Password` | False | string | Override the proxy password of the job's associated proxy |

Status URL requests

The **URL** needs to begin with either the *http://* or *https://* protocol and needs to be **URL** encoded. It can contain any of the following replacement values anywhere in the querystring. To include a replacement value, enclose it in percentage signs (e.g. %AgentID%).

- AgentID
- Agent.Name
- Agent.Description
- Agent.Domain
- JobID
- Job.Status
- Job.Created
- Job.Ended
- Job.Name
- Job.Description
- Job.ErrorCode
- Job.ErrorMessage
- Job.ErrorDetail
- Job.ErrorCount
- Job.Duration

**Note:** This **URL** can be executed multiple times during a **job’s** lifecycle, including the beginning and the end. Use the most recently passed status when making decisions.

### Request body (optional)

Define specific **fields** and values for each job that you create in bulk. You can format these in XML or in JSON.

Cancel URL **parameters**

- **URL** default **parameters** are overridden by their counterparts in the request body detail **parameters**.
- If there is an existing request body, `SplitJobs`in the **parameter URL** are cancelled.

#### XML

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `File` | False | XML | A **file** containing the detail parameters of the **jobs** to be created. `Post`using Content-Type `multipart/formdata`. |

```
<JobList>
    <Job>
        <Job.Description>Custom Description</Job.Description>
        <Job.Name>Custom Name</Job.Name>
        <AgentParameter.ViewIndexRange>1-199</AgentParameter.ViewIndexRange>
        <AgentParameter.ViewItemCount>998</AgentParameter.ViewItemCount>
        <Job.StatusUrl>http://myurl.com/?AgentID=%AgentID%</Job.StatusUrl>
        <Job.Geolocation>North America (Region)</Job.Geolocation>
    </Job>
    <Job>
        <Job.Description>Custom Description 2</Job.Description>
        <Job.Name>Custom Name 2</Job.Name>
        <AgentParameter.ViewIndexRange>200-</AgentParameter.ViewIndexRange>
        <AgentParameter.ViewItemCount>998</AgentParameter.ViewItemCount>
        <Job.StatusUrl>http://myurl.com/?AgentID=%AgentID%</Job.StatusUrl>
        <Job.ProxyPool>US1</Job.ProxyPool>
    </Job>
</JobList>
```

#### JSON

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `POSTDATA` | False | JSON | JSON array containing the detail parameters for the **jobs** to be created. `Post`using Content-Type `application/x-www-form-urlencoded`. |

```
[
    {
        "Job.Description": "Custom Description",
        "Job.Name": "Custom Name",
        "AgentParameter.ViewIndexRange": "1-199",
        "AgentParameter.ViewItemCount": "998",
        "Job.StatusUrl": "http://myurl.com/?AgentID=%AgentID%",
        "Job.Geolocation": "North America (Region)"
    },
    {
        "Job.Description": "Custom Description 2",
        "Job.Name": "Custom Name 2",
        "AgentParameter.ViewIndexRange": "200-",
        "AgentParameter.ViewItemCount": "998",
        "Job.StatusUrl": "http://myurl.com/?AgentID=%AgentID%",
        "Job.ProxyPool": "US1"
    }
]
```

### Responses

| Name | Type | Description |
| --- | --- | --- |
| `Result` | string | `Success` if the operation was successful. |
| `AgentID` | numeric | Unique identifier for the **agent**. |
| `JobID` | string | Unique identifier for the **job**. |
| `JobType` | string | The **job** type. |
| `ReportRefreshJobID` | string | Unique identifier for the `ReportRefreshJob`. |
| `JobList` | string | Lists the `JobID` and `JobType` of concurrent **job** runs. Responses for multiple **jobs** differ from responses for single **jobs**. |

Publishing and Querying

Publishing and viewing a query should be done once the `ReportRefreshData` **job** has been completed. This can be verified with a [Job.Get](/docs/agentrun#job-get) API request using the `ReportRefreshJobID` received in the `agent`. **Run** result as the value for the `JobID` parameter.

### Sample request

```
curl -X GET "https://api.mozenda.com/rest?WebServiceKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&Service=Mozenda10&Operation=Agent.Run&AgentID=1039&AgentParameter.Zip=90210"
```

### Sample responses

#### XML single job

```
<?xml version="1.0" encoding="utf-8"?>
<AgentRunResponse
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Result>Success</Result>
	<AgentID>1003</AgentID>
	<JobID>15852</JobID>
	<JobType>WebPageHarvest</JobType>
	<ReportRefreshJobID>15853</ReportRefreshJobID>
</AgentRunResponse>
```

#### XML multiple jobs

```
<?xml version="1.0" encoding="utf-8"?>
<AgentRunResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Result>Success</Result>
    <AgentID>1069</AgentID>
    <JobList>
        <Job>
            <JobID>12301</JobID>
            <JobType>WebPageHarvest</JobType>
        </Job>
        <Job>
            <JobID>12302</JobID>
            <JobType>WebPageHarvest</JobType>
        </Job>
        <Job>
            <JobID>12303</JobID>
            <JobType>WebPageHarvest</JobType>
        </Job>
        <Job>
            <JobID>12304</JobID>
            <JobType>ReportRefreshData</JobType>
        </Job>
    </JobList>
</AgentRunResponse>
```

#### JSON single job (add `&amp;ResponseFormat=JSON`)

```
{
  "AgentID": 1039,
  "JobID": 32483,
  "JobType": "WebPageHarvest",
  "ReportRefreshJobID": 32484,
  "JsonResult": {
    "Command": "Agent.Run",
    "AutoLoggedIn": false,
    "WebConsoleKey": "",
    "Result": "Success",
    "ErrorCode": "",
    "ErrorDescription": "",
    "ErrorList": [],
    "ExecutionTime": {
      "Ticks": 0,
      "Days": 0,
      "Hours": 0,
      "Milliseconds": 0,
      "Minutes": 0,
      "Seconds": 0,
      "TotalDays": 0,
      "TotalHours": 0,
      "TotalMilliseconds": 0,
      "TotalMinutes": 0,
      "TotalSeconds": 0
    }
  }
}
```

#### JSON multiple jobs (add `&amp;ResponseFormat=JSON`)

```
{
    "AgentID": 1069,
    "Job": [
        {
            "JobID": 12306,
            "JobType": "WebPageHarvest"
        },
        {
            "JobID": 12307,
            "JobType": "WebPageHarvest"
        },
        {
            "JobID": 12308,
            "JobType": "WebPageHarvest"
        },
        {
            "JobID": 12309,
            "JobType": "ReportRefreshData"
        }
    ],
    "JsonResult": {
        "Command": "Agent.Run",
        "AutoLoggedIn": false,
        "WebConsoleKey": "",
        "Result": "Success",
        "ErrorCode": "",
        "ErrorDescription": "",
        "ErrorList": []
    }
}
```