Getting Started

The Moz API is a JSON-RPC 2.0 API 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 after logging in or signing up for an account.

Quickstart

To get started right away, sign up for an API account if you don’t already have one and log in to the API dashboard to generate an API token. If you just want to test the API, you may there is an option to sign up for a free trial account with an ultra-low monthly access quota with the option to and upgrade later.

You should then be able to run the following code at no cost:

curl -X POST https://api.moz.com/jsonrpc \
-H "x-moz-token: <YOUR_MOZ_TOKEN>" \
-H "Content-Type: application/json" \
-d '
{
  "jsonrpc": "2.0",
  "id": "462119f8-8827-4702-b5d5-25a74171a3a9",
  "method": "quota.lookup",
  "params": {
    "data": {
      "path": "api.limits.data.rows"
    }
  }
}'

You can now learn more about authentication, pricing and quota, request construction, and rate limiting and error handling, 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, 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. 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). 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. For full details, please refer to the Moz API pricing page.

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:

• 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 provided must be at least 24 characters long. We recommend using a V4 UUID which you can generate online 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:

{
  "jsonrpc": "2.0",
  "id": "9df01fdb-e8ad-4639-b215-6029eb051997",
  "method": "data.global.top-pages.list",
  "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:

{
  "id": "890813fb-dc61-487e-8c7a-c0abc571425d",
  "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 for more details on common errors and mitigations.

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

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