Overview & Authentication - Moz API for Link Data V2
Frequently Asked Questions
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.
What's Covered?
This guide covers authentication and request format for the Moz Links API V2. It also covers common errors and response formats.
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:
- Access the Moz API dashboard at https://moz.com/api/dashboard
- Select + Add Token to generate a new token for API usage
- Enter a description for your token and click Create
- 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`.
![](https://moz.com/images/help/large/API-Token-Header.jpg?w=1234&h=314&auto=compress%2Cformat&fit=crop&dm=1690223506&s=d330b1afd843e2525b01e09515da6098)
Alternative (legacy) authentications:
- 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
- Moz Links API v1 Signed Authentication
For clients unable to connect over HTTPS, we also support Legacy Moz Links API v1 Signed Authentication over HTTP (see here.)
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.
Related Articles
Was this article helpful?
Yes! Amazing!
Yes! It was what I needed.
Meh. It wasn’t really what I was looking for.
No, it wasn’t helpful at all.
Thanks for the feedback.