The REST API is available to all Enterprise customers.
The Mozenda REST API allows you to control your agents and data collections without manually accessing the Web Console. The API can be used to run an agent, get data, check a job’s progress, and more. You can use the API to automate Mozenda-related operations within your own application.
An API call is a URL that invokes specific actions and/or retrieves data. The parameters that are included in the API call determine the actions performed, or what data is retrieved.
The API calls return XML containing the status and details of the made API call (like starting a new job, for example).
<?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> </AgentRunResponse>
|The job has successfully started for the specified agent.|
|Identifies the agent for which the job was run.|
|Provides the Job ID for your records, or for use in other API calls, such as |
|Identifies the type of job being executed.|
Understanding API calls
API calls can do many of the same things that can be done manually through the Web Console, such as running agents, canceling agents, or exporting agents’ data. Each major function of the Web Console has a corresponding API call.
For example, the
Agent.Run API call runs a new job for an agent. If we were to use the Mozenda API to run a new job for an agent with an ID of 1009, the API call would look like the following:
Each piece of information included in the API call is a parameter. Each parameter has a name and a value.
The first portion of the API call is the URL that seeks the Mozenda servers and identifies itself as an API call:
The next portion of the API call is the web service key, which specifies to the Mozenda servers which account the API is accessing and acts as a password to that account:
- Click here to find your web service key.
After the web service key is the parameter identifying the type of API call being made, which is standard to all Mozenda API calls:
After the service parameter, the operation parameter is used to specify which API call is being made (i.e., which Mozenda operation is to be carried out):
Finally, the agent ID parameter, which is required by the
Agent.Run API call, indicates which agent is to be run:
Most of the operations available through the REST API use
GET requests. We use a
POST request when the operation may require more data than can fit in the URL.
For example, to add data to a collection in bulk, you can use the
POST request version of
Collection.AddItem. In the Mozenda REST API Documentation, for operations that use
POST requests, it will specify the format of the data to be posted under the Request body subsection.
Attention! Requests usage limitations
When the request limit is exceeded, an HTTP error (429) will be returned.
The following limitations that the user will encounter are :
- A user is allowed up to 100 calls per minute.
- Example: If a user makes 20 calls every 10 seconds this will hit the first limitation.
- A user is allowed up to 20 calls "in the queue" (i.e. calls that have not yet returned a response).
- Example: If a user makes all 25 calls at the same time, this will hit the second limitation.
- Calls are handled serially - meaning first in, first out.
- Example: If a user initiates 10 calls, and call number 1 takes 45 seconds to complete, the second call will begin to be handled after 45 seconds.
To assist our users with using the API, we have created a Postman library with all of the API operations attached. You can access that here.