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

    Agent.Run

    • Updated on 14 May 2024
    • 3 Minutes to read
    • Contributors
    • Print
    • 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?
    What's Next