Agent.Run

25 May 2021
3 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Agent.Run

Updated on 25 May 2021
3 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

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 agent.
`Job.Geolocation`	False	string	Geographic identifier for the location of the job.
`Job.Name`	False	string	Unique identifier for the agent.
`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.

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

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, SplitJobsin 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 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 `&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 `&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": []
    }
}

Was this article helpful?

What's Next

Agent.DeleteCustomField

Agent.Run

Description

URL parameters

Request body (optional)

XML

JSON

Responses

Sample request

Sample responses

XML single job

XML multiple jobs

JSON single job (add &ResponseFormat=JSON)

JSON multiple jobs (add &ResponseFormat=JSON)

What's Next

JSON single job (add `&ResponseFormat=JSON`)

JSON multiple jobs (add `&ResponseFormat=JSON`)