Analytics API

Overview

The Analytics API offers organizations a programmatic way to obtain Grammarly usage data and integrate it directly into their business intelligence (BI) systems. This allows organizations to tie the data to key business outcomes and measure Grammarly’s impact more effectively.

This developer guide explains how to work with the Grammarly Analytics API. The API is intended for programmatic consumption. Organizations can access the API through an HTTP REST interface.

Get analytics for users

GET https://api.grammarly.com/ecosystem/api/v2/analytics/users/

This API endpoint retrieves a paginated list of users associated with a Grammarly subscription. Each user object in the response includes the user ID and Grammarly usage statistics.

The scope required for the Access token is analytics-api:read

Request Parameters

Parameter	Type	Required	Description
date_from	String	Yes	Start date for filtering user statistics in the YYYY-MM-DD format. The earliest supported start date is one year prior to the current date.
date_to	String	Yes	End date for filtering user statistics in the YYYY-MM-DD format. The latest supported date is two days before the current date.
cursor	String	No	Marker to paginate through large data sets. No cursor is required for the initial request. If additional pages are available, the response will contain a next_cursor value, which should be used as the cursor value in the subsequent request.
limit	Integer	No	Limit on the number of returned entries. The maximum value is 400. Must be a positive number.

Example Request

An example cURL request to get the first ten users:

curl -X GET \
'https://api.grammarly.com/ecosystem/api/v2/analytics/users?limit=10&date_from=2024-10-19&date_to=2024-10-22' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response Format

The response is a JSON object that includes an array of data objects and a paging object responsible for paging operations.

Response Parameters

Parameter	Type	Description
data	Array	An array of user objects containing user statistics details.
paging	Object	API paging object.

Each user object in the data array has the following structure:

Field	Type	Description
id	Integer	A unique identifier for the user.
name	String	Name of the user.
email	String	User’s email address.
days_active	Integer	The number of days a team member actively used Grammarly within the specified date range.
sessions_count	Integer	The number of writing sessions that took place during the specified date range. A writing session occurs when a team member uses Grammarly to actively write or edit text. A session automatically ends after 30 minutes of inactivity.
sessions_improved_percent	Float	The percentage of writing sessions that were improved out of writing sessions that had at least one error and took place during the selected date range. A writing session is considered improved if there are fewer mistakes in the text at the end of a session than at the beginning.
prompt_count	Integer	The number of generative AI prompts used by a team member within the date range.

paging object has the following structure:

Field	Type	Description
next_cursor	String	An encoded cursor that is used to fetch the next set of results, if available. It will not be returned if no more data is available.
cur_cursor	String	The cursor from the client request will be used if specified.
has_more	Boolean	Indicates whether there are additional records available in the database.
page_size	Integer	Number of items included in the data array in the current response.

Example Response

An example response body:

{
    "data": [
        {
            "id": 123,
            "name": "name",
            "email": "email.address@email.com",
            "days_active": 1,
            "sessions_count": 2,
            "prompt_count": 3,
            "sessions_improved_percent": 28.571428571428573
        }
    ],
    "paging": {
        "next_cursor": "MTI=",
        "cur_cursor": "xyZ",
        "has_more": true,
        "page_size": 1
    }
}

Data availability

The data is accessible for 365 days prior, with a two-day lag from the current date. For example, if you make a request on November 1, 2024, the valid date range for date_from and date_to would be between October 30, 2023 and October 30, 2024.