Moz API V2 Overview & Authentication

Frequently Asked Questions

  • Yes, the Links V1 endpoints are still accessible.
  • No, the same credentials are used for both versions of the Links API.
Have you heard? We've launched a brand new set of Moz API beta endpoints, including Keyword Suggestions, Search intent, Brand AuthorityTM, and more! To learn more and get started, check out the all-new documentation here.
Please note: Beginning August 8, 2024, Moz API will no longer support plain HTTP access. To avoid service disruption, please update any existing HTTP client configurations to HTTPS.

What's Covered?

This guide covers authentication and request format for the Moz Links API V2. It also covers common errors and response formats.

Please note: This guide refers to the overview and authentication of Moz Links API V2. If you are using Moz Links API V1, please see our V1 Authentication guide.

Quick Links

API Location

All links v2 API endpoints use the following base URL: https://lsapi.seomoz.com/v2/

The endpoint you are looking to request data from will need to be added to the base URL. For example, if you are looking to call data from the Anchor Text endpoint, the URL would be https://lsapi.seomoz.com/v2/anchor_text

Each endpoint URL can be verified within the Making Calls section of the Help Hub on the corresponding page.

Credentials

To access the Links v2 API, use your Moz API credentials API Token. To generate a token, follow these steps:

  1. Access the Moz API dashboard at https://moz.rankious.com/_moz/api/dashboard
  2. Select + Add Token to generate a new token for API usage
  3. Enter a description for your token and click Create
  4. You should now see your new token in the API Tokens section of the dashboard

Authentication

The token generated during sign-up simplifies the authentication process to access Moz API. When structuring your request, all you need to do is add your token as a header value with the key `x-moz-token`.

Alternative (legacy) authentication:
  • Basic Auth over HTTPS

    If you were a user of the Moz API before March 2024, you can authenticate requests via Basic Auth over HTTPS. Use your 'Access ID' as a username, and your 'Secret Key' as a password. If you are a legacy subscriber, this will be noted with a Legacy Token tag in your usage dashboard. Click Show legacy credentials to find your access ID and Secret Key.Mozscape Signed Authentication

Please note: Beginning August 8, 2024, Moz API will no longer support plain HTTP access. To avoid service disruption, please update any existing HTTP client configurations to HTTPS.

Request Format

All requests are structured as JSON, and must be sent as POST requests to their respective endpoints. The specific request syntax and parameters available for each endpoint are documented on their respective pages.

If you use Postman for making API calls, you can use the link here to import the Moz Links V2 API collection. This will provide real examples of each endpoint’s call format - you will just need to enter your Access ID and Secret Key within the Authentication tab and edit the body to request the data you’re looking for.

Successful Response Format

All successful responses are structured as JSON and are returned with HTTP status code 200. The specific syntax and elements for each endpoint are documented on their respective pages.

Error Response Format

All error responses are structured as JSON and are returned with an HTTP status code in the 4xx-5xx range.

The syntax for error responses is shared between all endpoints and is as follows:

{ "name": "string", "message": "string"}
  • name

    A short name for the error that is intended to remain fixed over time and be interpreted by programs.

    Type: string

  • message

    A description of the error that is intended to change over time and be interpreted by humans.

    Type: string

Common Errors

  • Bad Request

    Message: One or more input parameters are invalid.
    HTTP Status Code: 400

  • Not Authorized

    Message: Your authentication failed.
    HTTP Status Code: 401

  • Not Authorized

    Message: Your authentication has expired.
    HTTP Status Code: 401

  • Not Authorized

    Message: Your monthly row limit reached.
    HTTP Status Code: 401

  • Forbidden

    Message: Unrecognized API method.
    HTTP Status Code: 403

  • Forbidden

    Message: This account has been banned from this API.
    HTTP Status Code: 403

  • Forbidden

    Message: This account has been banned from Moz's APIs.
    HTTP Status Code: 403

  • Too Many Requests

    Message: This request exceeds the limit allowed by your current plan.
    HTTP Status Code: 429

  • Message: You are producing the error: URL must be ascii only

    To resolve: Use the punycode version of the URL


Versioning

The current version of the Links API is 2. This version is incremented when there is a breaking change to an endpoint's behavior so we can maintain backwards compatibility. Additional fields that do not change the meaning of existing fields and additional optional query parameters that do not change the default behavior are not considered breaking changes.

Getting Started Cheat Sheet

Keep everything you need to get started, all in one place. Download this handy PDF to have on hand as you work with the Moz API.

Preview of the PDF download.

Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.