--- title: "Mozenda REST API" slug: "rest-api-introduction" description: "The Mozenda API allows you to create, manage, and publish powerful web scraping projects without interacting with the Mozenda Web Console. " tags: ["python", "java", "JavaScript", "curl"] updated: 2024-05-14T14:21:52Z published: 2024-05-14T14:21:52Z canonical: "help.mozenda.com/rest-api-introduction" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.mozenda.com/llms.txt > Use this file to discover all available pages before exploring further. # REST API Introduction *The REST API is available to all [Enterprise and Professional](https://www.mozenda.com/pricing) 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). ### Sample response: ``` Success 1003 15852 WebPageHarvest ``` | Response | Meaning | | --- | --- | | `<Result>Success</Result>` | The **job** has successfully started for the specified **agent**. | | `<AgentID>1003</AgentID>` | Identifies the **agent** for which the **job** was run. | | `<JobID>15852</JobID>` | Provides the **Job ID** for your records, or for use in other *API* calls, such as `Job.Pause` or `Job.GetAgentProgress`. | | `<JobType>WebPageHarvest</JobType>` | 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: ``` https://api.mozenda.com/rest?WebServiceKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX&Service=Mozenda10&Operation=Agent.Run&AgentID=1009 ``` Each piece of information included in the *API* call is a **parameter**. Each **parameter** has a name and a value. | Name | Value | | --- | --- | | `WebServiceKey` | XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX | | `Service` | Mozenda10 | | `Operation` | Agent.Run | | `AgentID` | 1009 | ``` https://api.mozenda.com/rest?WebServiceKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX&Service=Mozenda10&Operation=Agent.Run&AgentID=1009 ``` The first portion of the *API* call is the **URL** that seeks the *Mozenda* servers and identifies itself as an *API* call: ``` https://api.mozenda.com/rest? ``` 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: ``` &WebServiceKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX ``` - [Click here](https://help.mozenda.com/docs/generate-your-web-service-key) 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: ``` &Service=Mozenda10 ``` 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): ``` &Operation=Agent.Run ``` Finally, the **agent ID** parameter, which is required by the `Agent.Run` *API* call, indicates which **agent** is to be run: ``` &AgentID=1009 ``` ### `GET` and `POST` requests 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 : 1. 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. 2. 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. 3. 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. ### Postman 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](https://documenter.getpostman.com/view/11188737/SzmY7fju?version=latest#d2ac1567-f054-4076-917a-179ab38606e2).