1. Help
  2. Moz API — Brand Authority
  3. Generate

Generate

Frequently Asked Questions

  • Calls to the Generate endpoint require 2 quota.

What’s Covered?

In this guide, you’ll learn more about making calls to the Generate 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 Generate endpoint is used to request a Brand Authoritytm score be generated for a site that doesn’t currently have a score in our database. When making a call to the Fetch endpoint, you may receive an error stating, “A Brand Authority score does not yet exist for the target URL specified.” In these cases, a score can be requested via the Generate endpoint. Learn more about Brand Authority in the Moz Learning Center.

Quick Links

Getting Started

Before making calls to the Generate 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 Generate endpoint method, be sure to use the following designation.

          
beta.data.metrics.brand.authority.generate

Request Parameters Syntax

Generating and returning a Brand Authority score requires two separate calls to be made, the first to generate the score itself, and the second the look up the score that was generated asynchronously. For information on the second call, please see our Async Call Lookup guide.

          
"data": {
    "query": "string"
}

Example JSON Request

          
{
  "jsonrpc": "2.0",
  "id": "b8d5f7b3-7d77-4c4a-9f7b-4fa7f46bcc62",
  "method": "beta.data.metrics.brand.authority.generate",
  "params": {
    "data": {
        "query": "moz.com"
    }
  }
}

Request Parameters

“auth” — The authorization object

  • Type: object
  • Required: yes

“auth.token_id” — The unique token from your API dashboard

  • Type: string
  • Required: yes

“data” — The data object

  • Type: object
  • Required: yes

“data.query” — The URL to generate a Brand Authority score for

  • Type: string
  • Required: yes

Response Syntax

The initial call to generate a Brand Authority score will return an object describing the quota used for the request and a reference to an async_call. The async_call object is used to represent background processing that the API is performing on the client’s behalf. It is expected that the client will poll the Async Call Lookup end-point to check the status of the async_call and to receive the ultimate result for the work.

The final response that is returned for this end-point is found in the result attribute of the completed async_call object. That will include the requested brand authority score.

Initial 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
      },
      "async_call": {
          "id": "string",
          "action": “string”,
          "status": “string”,
          "ttl": number,
          "result": object | null,
          "error": object | null
      }
   }
 }

Final Response Syntax

          
{
	"id": "string",
	"jsonrpc": "string",
	"result": {
		"async_call": {
			"id": "string",
			"action": "BetaDataMetricsBrandAuthorityGenerate",
			"status": "string",
			"ttl": number,
			"result": {
				"brand_authority_score": number,
				"query": "string"
			}
		}
	}
}

Example JSON Response

          
{
    "id": "77fbd6b5-5712-4a98-b965-708ec3a0f58d",
    "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": 2
        },
        "async_call": {
            "id": "8ba32d29-c901-4e13-b30e-18c2b4547f93",
            "action": "BetaDataMetricsBrandAuthorityGenerate",
            "status": "pending",
            "ttl": 30,
            "result": "null",
            "error": "null"
        }
    }
}

Response Elements

“result” — An object containing the response provided by the endpoint’s asynchronous call

  • 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 decremented 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 resent

  • 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 invocation

  • Type: number

“result.async_call” — An object containing the details returned by the action’s asynchronous call at the time of data generation.

  • Type: Object

“result.async_call.id” — The unique call id assigned to the Brand Authority generation performed. This id can be used to confirm the Brand Authority score generated for the input query

  • Type: String

“result.async_call.action” — The method used for the asynchronous call. This will always reflect the method in the payload of the initial call — BetaDataMetricsBrandAuthorityGenerate

  • Type: String
  • Value: BetaDataMetricsBrandAuthorityGenerate

“result.async_call.status” — The current status of the asynchronous action to generate a Brand Authority score

  • Type: String
  • Expected values: “initializing”, “pending”, “processing”, “complete”
  • When running the action, expect the status in the response to be “pending”

“result.async_call.ttl” — The time-to-live for the pending call, defaulted to 30 seconds

  • Type: Number
  • Value: 30

“result.async_call.result” — The final return from the action, representing the generated Brand Authority score. Given that this call is made asynchronously, expect the initial value to be “null”.

  • Type: Object or null

“result.async_call.error” — An object containing error details if the call has failed

  • Type: Object or null

Once you have called the above endpoint and received a successful response, you can then look up the results of the enqueued action by using the Async Call Lookup endpoint. We recommend requesting the status every 5 seconds until the request is complete. For more information on the Async Call Lookup guide.

Limits

Quota Usage

  • Using this endpoint will consume two units of quota; the path and quota amount used will both be noted within the quota object of the call response

  • If you are looking to fetch the existing Brand Authority score for a query, check out the Brand Authority fetch endpoint

  • Check out your API dashboard to manage your tokens, and review your remaining quota

Errors

Please note that any call resulting in an error message will not decrease your quota.

See the Common Errors section for errors that are common to all endpoints.

Example HTTP Request

          
POST /jsonrpc HTTP/1.1
POST /jsonrpc?= HTTP/1.1
Content-Type: application/json
Host: api.moz.com
Content-Length: [length of request payload in bytes]
{
  "jsonrpc": "2.0",
  "id": "71a0416d-ca47-4b27-be3e-92033e289d5b",
  "method": "beta.data.metrics.brand.authority.generate",
  "params": {
    "data": {
	  "query": "moz.com"
    }
  }
}

Example cURL Request

          
curl --request POST \
  --url 'api.moz.com/jsonrpc' \
  --header 'Content-Type: application/json' \
--header 'x-moz-token: [[YOUR TOKEN HERE]]' \
  --data '{
    "jsonrpc": "2.0",
    "id": "b1e0b86a-2e0d-479e-99e4-165e3b2b19e5",
    "method": "beta.data.metrics.brand.authority.generate",
    "params": {
	"data": {
	    "query": "moz.com"
	}
    }
  }'

Example Python Request

          
import requests
url = "api.moz.com/jsonrpc"
querystring = {"":""}
payload = {
  "jsonrpc": "2.0",
  "id": "580547ab-7939-4f34-879d-1da504313e50",
  "method": "beta.data.metrics.brand.authority.generate",
  "params": {
    "data": {"query": "moz.com"}
  }
}
headers = {"Content-Type": "application/json"}
response = requests.request("POST", url, json=payload, headers=headers,
params=querystring)
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 Generate action outlined in red.

Was this article helpful?

Thanks for the feedback.

Contact the Help Team if you have a specific question.
Cancel

Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.