Agent.Run
  • 14 May 2024
  • 3 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Agent.Run

  • Dark
    Light
  • PDF

Article summary

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.

NameRequiredTypeDescription
AgentIDTruenumericUnique identifier of the agent.
AgentParameter.<AgentParameterName>FalsestringParameter you would like applied to the job for the agent to run.
Job.DescriptionFalsestringA description of the agent.
Job.GeolocationFalsestringGeographic identifier for the location of the job.
Job.NameFalsestringUnique identifier for the agent.
Job.ProxyPoolFalsestringA custom, third-party proxy pool identifier for the job.
Job.StatusTimeoutFalsestringThe maximum amount of time in seconds that the application will attempt to request a Job.StatusURL.
Job.StatusURLFalsestringA URL that the application will request when the status of the job updates.
ReportRefresh.StatusUrlFalsestringA URL that the application will request when the status of the ReportRefreshData job updates.
CollectionCombinedRebuild.StatusURLFalsestringA URL that the application will request when the status of a combined collection job updates.
SplitJobsFalsenumericParameter 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

NameRequiredTypeDescription
FileFalseXMLA file containing the detail parameters of the jobs to be created. Postusing 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

NameRequiredTypeDescription
POSTDATAFalseJSONJSON array containing the detail parameters for the jobs to be created. Postusing 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

NameTypeDescription
ResultstringSuccess if the operation was successful.
AgentIDnumericUnique identifier for the agent.
JobIDstringUnique identifier for the job.
JobTypestringThe job type.
ReportRefreshJobIDstringUnique identifier for the ReportRefreshJob.
JobListstringLists 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?