Fetch
Frequently Asked Questions
What’s Covered?
In this guide, you’ll learn more about making calls to the Fetch endpoint method for the Moz API.
Please note: This guide refers to the overview and authentication of the Moz API for requesting Brand Authority data. For documentation regarding the Moz API for links data, please see our Moz API — Links documentation.
What is this endpoint for?
The Fetch endpoint is used to request Brand Authoritytm from the Moz API. This is the same metric seen in the Domain Overview tool of Moz Pro. Use this metric to understand the strength of your website’s brand, benchmark against competitors, and more. Learn more about Brand Authority in the Moz Learning Center.
Quick Links
Getting Started
Before making calls to the Fetch endpoint method, be sure you are set up with a Moz API token within your Moz account. If you need help with generating a token, please see our getting started guide. Please note: If you currently have a Moz API access ID for links data, you will need a separate key to access Brand Authority.
Endpoint Method
When requesting data from the Fetch endpoint method, be sure to use the following designation.
beta.data.metrics.brand.authority.fetch
Request Parameters Syntax
"data": {
"query": "string",
}
Example JSON Request
{
"jsonrpc": "2.0",
"id": "b8d5f7b3-7d77-4c4a-9f7b-4fa7f46bcc62",
"method": "beta.data.metrics.brand.authority.fetch",
"params": {
"data": {
"query": "moz.com"
}
}
}
Request Parameters
“data” – The data object
- Type: object
- Required: yes
“data.query” — The URL you’re requesting Brand Authority for
- Type: string
- Required: yes
Response Syntax
{
"id": "string",
"jsonrpc": "string",
"result": {
"quota": {
"path": "string",
"account_id": number,
"allotted": number,
"used": number,
"reset": "string",
"overage": boolean,
"period_start": number,
"period_reset": number,
"usage_key": null,
"usage_value": number
},
"brand_authority_score": number,
"query": "string”,
}
}
Example JSON Response
{
"id": "b48e0850-1bff-4b0d-9f1f-f153f5c8b185",
"jsonrpc": "2.0",
"result": {
"quota": {
"path": "api.limits.beta.metrics.brand_authority",
"account_id": 10430243,
"allotted": 5,
"used": 2,
"reset": "month",
"overage": false,
"period_start": 1688194800,
"period_reset": 1690873200,
"usage_key": null,
"usage_value": 1
},
"brand_authority_score": 56,
"query": "moz.com"
}
}
Response Elements
“result” — An object containing the returned response
- Type: Object
“result.quota” — An object detailing quota usage for the current call
- Type: number
“result.quota.path” — The specific path attributed to the call that quota is used against
- Type: string
“result.quota.account_id” — Your account id
- Type: number
“result.quota.allotted” — The total available quota allotted for the given period
- Type: number
“result.quota.used” — The amount of quota used in the current period
- Type: number
“result.quota.reset” — The frequency of which quota is reset
- Type: string
- Expected values: “daily”, “weekly”, “monthly”, “never”
“result.quota.overage” — Determines whether quota overage is allowed
- Type: boolean
“result.quota.period_start” —The Unix timestamp of when the current quota period started
- Type: number
“result.quota.period_reset” — The Unix timestamp of when the current quota period will expire and quotas will reset
- Type: number
“result.quota.usage_key” — The usage key, if required for a given quota
- Type: null
“result.quota.usage_value” — The amount of quota used for this request
- Type: number
“result.brand_authority_score” — The Brand Authority score for the given target URL
- Type: number
“result.query” — The target URL associated with the retrieved Brand Authority score
- Type: string
Limits
Quota Usage
Using this endpoint will consume one unit of quota; the path and quota amount used will both be noted within the quota object of the call response
- Quota will not be used if a Brand Authority score does not exist upon call return. See the Errors section of this page to learn more.
If you are looking to generate a Brand Authority score for a query that has not yet been created, check out the Brand Authority generate endpoint
Check out your API dashboard to manage your tokens, and review your remaining quota usage
Errors
Please note that any call resulting in an error message will not decrease your quota.
- Score does not exist. A brand authority score does not yet exist for the target URL specified. This means that you will want to first generate a score using the Brand Authority Generate action.
{
"id": "befeab5e-33e0-48c9-9679-b72c739cddd0",
"jsonrpc": "2.0",
"error": {
"code": -32655,
"status": 404,
"data": {},
"message": "A brand authority score does not exist for that target. Call BetaDataMetricsBrandAuthorityGenerate to have one generated."
}
}
See the Common Errors section for errors that are common to all endpoints
Example HTTP Request
POST /jsonrpc HTTP/1.1
Content-Type: application/json
Host: api.moz.com
Content-Length: 345
{
"jsonrpc": "2.0",
"id": "0dbfc494-e209-4f6f-b0a2-8bc72ddef06e",
"method": "beta.data.metrics.brand.authority.fetch",
"params": {
"data": {
"query": "moz.com"
}
}
}
Example cURL Request
curl --request POST \
--url https://api.moz.com/jsonrpc \
--header 'Content-Type: application/json' \
--header 'x-moz-token: [[YOUR TOKEN HERE]]' \
--data '{
"jsonrpc": "2.0",
"id": "880de189-de78-481d-8549-450cb72d8060",
"method": "beta.data.metrics.brand.authority.fetch",
"params": {
"data": {
"query": "moz.com"
}
}
}'
Example Python Request
import requests
url = "https://api.moz.com/jsonrpc"
payload = {
"jsonrpc": "2.0",
"id": "ff0f4bf4-f15c-4c31-a4d6-340fe348a062",
"method": "beta.data.metrics.brand.authority.fetch",
"params": {
"data": {"query": "moz.com"}
}
}
headers = {"Content-Type": "application/json"}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
Overview of API Endpoint Methods
The Moz API for Brand Authority consists of 3 primary endpoint methods: Fetch, Generate, and Async. Below is a diagram of how these methods work together with the Fetch action outlined in red.
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.