Agent.Run
  • 25 May 2021
  • 3 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Agent.Run

  • Dark
    Light
  • PDF

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. 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

Name Required Type Description
POSTDATA False JSON JSON 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

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?