Step 1: Create a Report

Analytics are provided in reports, which can be provided either synchronously or asynchronously. The latter approach is recommended whenever you want to fetch a large amount of data; it requires two API calls — one to tell Yext’s servers to create a report and a second to retrieve the report.

We’ll talk about the asynchronous reports a bit later, but for now let’s create a simple, synchronous report.

Synchronous reports

To create a report and get the results immediately, send the following API request:

POST: https://api.yext.com/v2/accounts/me/analytics/reports?api_key=API_KEY&v=YYYYMMDD

Header

Content-Type: application/json

Body

{
  "metrics": [
    "ANSWERS_SEARCHES"
  ],
  "dimensions": [
    "DAYS"
  ],
  "filters": {
    "startDate": "2021-04-01",
    "endDate": "2021-01-05"
  }
}

This report returns the number of Searches that were run by day from April 1, 2021 through April 5, 2021. If the request is successful, you should receive the following response:

{
    "meta": {
        "uuid": "0179fc77-87bb-2196-4da3-da130e410cd8",
        "errors": []
    },
    "response": {
        "data": [
            {
                "ANSWERS_SEARCHES": 1282,
                "day": "2021-04-01"
            },
            {
                "ANSWERS_SEARCHES": 1178,
                "day": "2021-04-02"
            },
            {
                "ANSWERS_SEARCHES": 262,
                "day": "2021-04-03"
            },
            {
                "ANSWERS_SEARCHES": 256,
                "day": "2021-04-04"
            }
        ]
    }
}

Asynchronous reports

With the synchronous call above, we created a simple report that returned results immediately, so now let’s try creating an asynchronous report.

Using the same call as before we can create an async report by adding &async=true to the Analytics Endpoint URL:

POST https://api.yext.com/v2/accounts/me/analytics/reports?api_key=API_KEY&v=YYYYMMDD&async=true

Header

Content-Type: application/json

Body

{
  "metrics": [
    "ANSWERS_SEARCHES"
  ],
  "dimensions": [
    "DAYS"
  ],
  "filters": {
    "startDate": "2021-04-01",
    "endDate": "2021-04-05"
  }
}

However, this time, the response body should look like the example below:

{
  "meta": {
    "uuid": "6c524b78-9356-4f06-8966-4e08e84abf8b",
    "errors": []
  },
  "response": {
    "id": "5163607c-1386-4d82-989b-61e7f8340ff8"
  }
}

You’ll now see the response field contains only an id. This value corresponds to the analytics report Yext is generating using the criteria specified in the API call.

You can see the status of the report by making the following API call:

GET https://api.yext.com/v2/accounts/me/analytics/standardreports/REPORT_ID?api_key=API_KEY&v=YYYYMMDD

This should return a response like the one below:

{
  "meta": {
    "uuid": "558c12d5-fff2-4634-a6ed-5c8ebcaca2a5",
    "errors": [
    ]
  },
  "response": {
    "status": "DONE",
    "url": "https:\/\/yext.analytics.s3.amazonaws.com\/api\/async\/current\/reports\/20211017_101800_5163607c-1386-4d82-989b-61e7f8340ff8_start-date_2021-04-01_end-date_2021-04-05.csv"
  }
}

The URL returned will provide a CSV file with the requested report.

In the event where the report has not yet been generated, the status will appear as PENDING and the url field will remain blank. Typically reports should generate within a few seconds although larger reports may take longer. To confirm your report is complete, continue polling this endpoint until response status equals DONE.