# Getting Started The Moz API is a [JSON-RPC 2.0 API](https://www.jsonrpc.org/specification) where procedures or methods are accessed through HTTP POST requests to a universal endpoint, `https://api.moz.com/jsonrpc`. The method name specified in the request body identifies the desired operation. The API provides access to a range of SEO-related data such as links and keyword metrics. The sidebar to the left gives an at-a-glance overview of the various resources that are accessible via the Moz API. Requests are authenticated by including a secret key (i.e. your Moz API token) in the custom `x-moz-token` header when making a POST request to `https://api.moz.com/jsonrpc`. Tokens can be generated on the [Moz API dashboard](https://moz.com/api/dashboard) after logging in or [signing up for an account](https://moz.com/products/api/pricing). ## Quickstart To get started right away, [sign up for an API account](https://moz.com/products/api/pricing) if you don’t already have one and [log in to the API dashboard](https://moz.com/api/dashboard) to generate an API token. If you just want to test the API, you may sign up for a free trial account with an ultra-low monthly access quota with the option to upgrade later. You should then be able to run the following code at no cost: ```bash curl -X POST https://api.moz.com/jsonrpc \ -H "x-moz-token: " \ -H "Content-Type: application/json" \ -d ' { "jsonrpc": "2.0", "id": "", "method": "quota.lookup", "params": { "data": { "path": "api.limits.data.rows" } } }' ``` ```python endpoint_url = "https://api.moz.com/jsonrpc" # Replace with your actual API token copied from the Moz API dashboard api_token = "" # Define your request headers with the custom API token headers = { "x-moz-token": api_token, "Content-Type": "application/json", } # Sample payload for a request which won't use any quota: request_body = { "jsonrpc": "2.0", "id": "", "method": "quota.lookup", "params": { "data": { "path": "api.limits.data.rows" } } } # Send the POST request with authentication response = requests.post(endpoint_url, headers=headers, json=request_body) # Print the response print(response.text) ``` ```javascript const endpointUrl = "https://api.moz.com/jsonrpc"; // Replace with your actual API token copied from the Moz API dashboard const apiToken = ""; // Sample payload for a request that won't use any quota: const requestBody = { jsonrpc: "2.0", id: "", method: "quota.lookup", params: { data: { path: "api.limits.data.rows", }, }, }; // Define the request options including headers const requestOptions = { method: "POST", headers: { "Content-Type": "application/json", "x-moz-token": apiToken, }, body: JSON.stringify(requestBody), }; // Send the POST request try { const response = await fetch(endpointUrl, requestOptions); const data = await response.json(); // Handle response data console.log(data); } catch (error) { console.error("Error:", error); } ``` You can now learn more about [authentication](https://moz.com/api/docs/guides/authentication), [pricing and quota](https://moz.com/api/docs/guides/getting-started#pricing-and-quota), [request construction](https://moz.com/api/docs/guides/getting-started#request-construction), [compression](https://moz.com/api/docs/guides/getting-started#compression), [rate limiting and error handling](https://moz.com/api/docs/guides/error-handling), and [asynchronous API calls](https://moz.com/api/docs/guides/asynchronous-api-calls), or browse the API methods in the left nav. You can then adapt the sample code above by changing the value of the `method` field in the request body to the name of the method you wish to access and updating the information in `params > data` to correspond with the method-specific parameters as described in the method documentation. ## Pricing and Quota The Moz API follows a [tiered pricing model](https://moz.com/products/api/pricing), where each tier gives access to a certain amount of quota per month. Quota is measured in rows, with one row typically corresponding to one object in the response for methods that return multiple objects, or one field in the response for methods that return a single flat object or report. Quota consumption after running a method is reported in the response body, allowing users to monitor and manage their usage effectively. Users can also track their remaining quota by accessing the [fetch quota method](https://moz.com/api/docs/methods/QuotaLookupAction). Users of the Moz API may have access to multiple types of quota (for example, users on the $20/month tier and higher receive a bonus quota for [beta methods](https://moz.com/api/docs/guides/getting-started#beta-methods)). The documentation for each method will provide specific information about the number of rows consumed by that method, as well as which quota it uses. To help illustrate how quota translates to concrete use cases, here are a couple of hypothetical examples of Moz API usage: - For 750 rows/month, you can track site metrics such as Domain Authority and link counts for 25 pages or domains daily - For 120,000 rows/month, you can pull up to 100,000 links pointing at any target, track URL metrics for over 500 domains daily, and have room left over to audit site migrations with the final redirect method or track your link acquisition campaigns with link status Some tiers also include options for pay-as-you-go overages. Users can upgrade, downgrade, or cancel their paid accounts via the [Moz API dashboard](https://moz.com/api/dashboard). For full details, please refer to the [Moz API pricing page](https://moz.com/products/api/pricing). ## Request Construction The payload of every request to `https://api.moz.com/jsonrpc` should be a JSON object which includes the following fields, following the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#request_object): - `jsonrpc`: This should always be set to 2.0 - `id`: This is not your Moz API token, but rather a unique identifier you provide. This ID is required per the JSON-RPC 2.0 specification and is used to support request batching. The value must be longer than 24 characters, and may contain only letters, numbers and hyphens. We recommend using a V4 UUID, which satisfies both rules and which you can generate [online](https://www.uuidgenerator.net/version4) or using whatever method you prefer. - `method`: This field identifies the desired operation to perform, as specified in the method documentation. - `params`: In the Moz API, this field will always include a nested data object which contains the method-specific request body, such as method parameters, sorts, and filters Here's an example JSON object describing the body of a valid request to the Moz API: ```json { "jsonrpc": "2.0", "id": "", "method": "quota.lookup", "params": { "data": { "path": "api.limits.data.rows" } } } ``` ## Response Handling Successful responses will include a JSON response body with some metadata (namely the client ID specified in the request and the JSONRPC version) and a “result” field containing the requested data, an echo of the original request, and a report on quota consumed. Here is an example of the body of a successful response: ```json { "id": "", "jsonrpc": "2.0", "result": { "serp_query": { "keyword": "domain authority", "locale": "en-US", "device": "desktop", "engine": "google", "vicinity": "" }, "keyword_metrics": { "volume": 2200, "difficulty": 69, "organic_ctr": 79, "priority": 57 } } } ``` Unsuccessful responses will come with the appropriate HTTP status code as well as a JSON body containing an explanatory message about the encountered issue. See the [error handling guide](https://moz.com/api/docs/guides/error-handling) for more details on common errors and mitigations. ## Compression The Moz API supports gzip compression in both directions, and the two are independent — you can compress the requests you send, ask for compressed responses, or both. ### Compressing the requests you send Include a `Content-Encoding: gzip` header and send a gzipped body. This is worth doing for large payloads: batched requests and methods that accept long lists of targets or keywords are highly repetitive, so they compress extremely well. If you are sending small, single-method requests, compression will not gain you much and can safely be skipped. ```bash printf '%s' '{ "jsonrpc": "2.0", "id": "", "method": "quota.lookup", "params": { "data": { "path": "api.limits.data.rows" } } }' | gzip -c > body.gz curl -X POST https://api.moz.com/jsonrpc \ -H "x-moz-token: " \ -H "Content-Type: application/json" \ -H "Content-Encoding: gzip" \ --data-binary @body.gz ``` ```python import gzip import json import requests request_body = { "jsonrpc": "2.0", "id": "", "method": "quota.lookup", "params": {"data": {"path": "api.limits.data.rows"}}, } headers = { "x-moz-token": api_token, "Content-Type": "application/json", "Content-Encoding": "gzip", } payload = gzip.compress(json.dumps(request_body).encode("utf-8")) response = requests.post(endpoint_url, headers=headers, data=payload) ``` ```javascript import { gzipSync } from "node:zlib"; const requestBody = { jsonrpc: "2.0", id: "", method: "quota.lookup", params: { data: { path: "api.limits.data.rows" } }, }; const response = await fetch(endpointUrl, { method: "POST", headers: { "Content-Type": "application/json", "Content-Encoding": "gzip", "x-moz-token": apiToken, }, body: gzipSync(JSON.stringify(requestBody)), }); ``` Two things to be aware of: - The maximum request body size is **100 KB**, measured **after** decompression. Compressing a payload reduces the bandwidth it uses but does not allow you to send more data than an uncompressed request. A body over that limit is rejected with **HTTP 413**. - A truncated or corrupt gzip body cannot be read, and the request is rejected. If you compress requests, make sure the full body is transmitted. ### Requesting compressed responses Include an `Accept-Encoding: gzip` header and successful responses will be returned gzip-encoded. This is the more valuable direction for most callers, because responses are usually much larger than requests. It is most noticeable on methods that return many rows — link and keyword list methods, and full SERP results. A response measuring 15,421 bytes is returned in 387 bytes, a reduction of around 97.5%. Most HTTP clients request and transparently decompress gzip responses already, so you may be benefiting from this without having configured anything. `curl` does so with `--compressed`, Python's `requests` does it by default, and so does `fetch` in Node.js. If you are using one of those, there is nothing to change. Error responses are returned uncompressed regardless of this header. They are small enough that compression would make no meaningful difference. ```bash curl -X POST https://api.moz.com/jsonrpc \ -H "x-moz-token: " \ -H "Content-Type: application/json" \ --compressed \ -d ' { "jsonrpc": "2.0", "id": "", "method": "quota.lookup", "params": { "data": { "path": "api.limits.data.rows" } } }' ``` ```python headers = { "x-moz-token": api_token, "Content-Type": "application/json", "Accept-Encoding": "gzip", } response = requests.post(endpoint_url, headers=headers, json=request_body) ``` ```javascript const response = await fetch(endpointUrl, { method: "POST", headers: { "Content-Type": "application/json", "Accept-Encoding": "gzip", "x-moz-token": apiToken, }, body: JSON.stringify(requestBody), }); ``` ## Method Structure Method names follow a consistent pattern, typically comprising of a top-level namespace, parent resource name (such as `keyword` or `link`), sub-resource names if applicable (such as `link.final-redirect`), and ending with a verb that describes the action to be performed on the specified resource (such as `fetch`, `list`, or `generate`). Adjective or adverb-style modifiers may be added if necessary to ensure clarity and reduce the need for complicated request parameter patterns, for example `recently-gained.list` or `search.by`. ## Endpoints vs. Methods Unlike an HTTP REST API, the Moz API exposes a single URL that accepts remote procedure calls. Therefore, we don't talk about "endpoints" in this documentation (a distinct URL + HTTP method which corresponds with some action on a resource), but rather "methods" (the name of the function to be executed by the API server). The method name is passed in the body of the request to the API URL, as per the [JSON-RPC 2.0 spec](https://www.jsonrpc.org/specification). For developers who are more familiar with HTTP REST patterns, you can think of the Moz API methods as playing a similar role to HTTP endpoints. ## Beta Methods At various points in time, you may notice methods in the left-hand nav marked with a `Beta` chip. These methods are available to users on the Starter Medium plan and higher. Beta methods draw from a separate quota than non-beta methods, which means that any requests made to these methods do not reduce the quota available on your main plan or incur overages. The amount of beta quota you have available depends on [your API pricing tier](https://moz.com/products/api/pricing#compare-plans-at-a-glance). When using beta methods, you may find that the available data is limited or different from what's available in Moz Pro. Feel free to [send us your feedback](mailto:api@moz.com) anytime! Note that **beta methods are subject to change or removal without notice at any time, and data or functionality accessed through beta methods may only be used for prototyping or internal business services**. The full terms of use for the Moz API beta can be found on the [Moz API legal page](https://moz.com/help/links-api/getting-started/legal). Please ensure you have reviewed and are in agreement with these terms of use before accessing beta methods. ## Versioning The API is currently not versioned, with no expected breaking changes except for endpoints marked as beta. Beta endpoints should not be relied upon for critical purposes, as they may undergo modifications or removal without prior notice. For full details, see [Moz API legal](https://moz.com/help/links-api/getting-started/legal).

Loading...

Lookup Account

id

account