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 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:
You can now learn more about
authentication,
pricing and quota,
request construction,
compression,
rate limiting and error handling,
and
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, 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 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 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:
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:
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.
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.
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.
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.