Async Call Lookup
Frequently Asked Questions
What’s Covered?
In this guide, you’ll learn more about making calls to the Async Call Lookup 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 Async Call Lookup endpoint is used to fetch the status of work that is being done in the background on behalf of a previous request. Clients are expected to poll this endpoint (request it repeatedly with a delay in between requests) until the returned async_call has a status of completed. The final format of the returned async_call may include either a result attribute (if the work was successful) or an error attribute (if the work failed).
As an example, a client may call the Brand Authority Generate end-point to request a score to be generated on-demand. That end-point will return an async_call object with an id attribute. The client should then repeatedly make requests to the Async Call Lookup end-point to wait for the work to be completed. Learn more about Brand Authority in the Moz Learning Center.
Quick Links
Getting Started
Before making calls to the Async Call Lookup 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 Links API access ID, you will need a separate key to access the Brand Authority in the Moz API.
Endpoint Method
When requesting data from the Async Call Lookup endpoint method, be sure to use the following designation.
async.call.lookup
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 first call, please see our Generate guide.
"data": {
"id": "8ba32d29-c901-4e13-b30e-18c2b4547f93"
}
Example JSON Request
{
"jsonrpc": "2.0",
"id": "71a0416d-ca47-4b27-be3e-92033e289d5b",
"method": "async.call.lookup",
"params": {
"data": {
"id": "8ba32d29-c901-4e13-b30e-18c2b4547f93"
}
}
}
Request Parameters
- “data.id” - The unique id of the asynchronous job you want to retrieve. This id should be the async_call.id provided in the response of any API calls that exhibit an asynchronous request. This id is returned when making a request to the Generate endpoint.
Response Syntax
{
"id": "string",
"jsonrpc": "string",
"result": {
"async_call": {object}
}
}
Example JSON Response
{
"id": "4d0b083f-a8bc-472a-ac3f-37cd5a68198d",
"jsonrpc": "2.0",
"result": {
"async_call": {
"id": "8ba32d29-c901-4e13-b30e-18c2b4547f93",
"action": "BetaDataMetricsBrandAuthorityGenerate",
"status": "complete",
"ttl": 10,
"result": {
"brand_authority_score": 56,
"query": "moz.com"
},
"error": null
}
}
}
Response Elements
“result” - An object containing the response provided by the endpoint’s asynchronous call
- Type: Object
“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 ID of the Async Call.
- Type: String
“result.async_call.action” — The original action that was called to initiate the Async Call.
- Type: String
“result.async_call.status” — The status of the call. This will be one of the following: initializing, pending, processing, complete
- Type: String
- When the status changes to “complete”, the returned object will also include either a non-null result or non-null error attribute.
“result.async_call.ttl” — How long (in seconds) the call will persist for. If the call times out it will return a NotFoundError when subsequent Async Call Lookup calls are made.
- Type: Number
“Result.async_call.result” – The ultimate result of the processed async_call — will reflect the structure of the original result.async_call.action response.
- Type: Object or null (if not yet completed, or an error occurred)
“result.async_call.error” — The error that occurred if the async_call failed to process. This will be in the same format as an error attribute for the entire JSON-RPC request.
- Type: Object or null (if not yet completed, or no error occurred)
Limits
Quota Usage
Looking up an asynchronous call does not consume any quota
Errors
Please note that any call resulting in an error message will not decrease your quota.
Call not found. This response is encountered if the id you’ve entered is incorrect and does not match any associated with an asynchronous call. It is also possible that you waited too long and the call has timed out; we recommend looking up asynchronous calls immediately after one is made.
{
"id": "b8c3b548-70be-45f8-b60d-6911c71c8184",
"jsonrpc": "2.0",
"error": {
"code": -32655,
"status": 404,
"data": {},
"message": "Call was not found."
}
}
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: 181
{
"jsonrpc": "2.0",
"id": "5724afb1-4671-41e1-af79-b7d3698e0b30",
"method": "async.call.lookup",
"params": {
"data": {
"id": "b65c4722-5285-405d-a564-e23590e05788"
}
}
}
Example cURL Request
curl --request POST \
--url https://api.moz.com \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"id": "0cab0fd8-d4e5-4ad0-9812-0dcc69b9f178",
"method": "async.call.lookup",
"params": {
"data": {
"id": "b65c4722-5285-405d-a564-e23590e05788"
}
}
}'
Example Python Request
import http.client
conn = http.client.HTTPSConnection("app-api-dynamic-arbiter.app-dev-dev.aws.moz.com")
payload = {
"jsonrpc": "2.0",
"id": "5724afb1-4671-41e1-af79-b7d3698e0b30",
"method": "async.call.lookup",
"params": {
"data": {
"id": "b65c4722-5285-405d-a564-e23590e05788"
}
}
}
headers = {
'Content-Type': "application/json"
}
conn.request("POST", "/jsonrpc", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
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 Async 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.