Analytics - Introduction

• AWS North America (AWS NA): https://app.contentstack.com
• AWS Europe (AWS EU): https://eu-app.contentstack.com
• AWS Australia (AWS AU): https://au-app.contentstack.com
• Azure North America (Azure NA): https://azure-na-app.contentstack.com
• Azure Europe (Azure EU): https://azure-eu-app.contentstack.com
• GCP North America (GCP NA): https://gcp-na-app.contentstack.com
• GCP Europe (GCP EU): https://gcp-eu-app.contentstack.com

NoteThe Analytics API may not be enabled by default for your organization. Reach out to our support team to get it enabled.

The Analytics APIs in Contentstack provide access to comprehensive insights into your organization’s usage, performance, and overall system health. Built on the unified Analytics platform, these APIs consolidate data across key products such as CMS, Launch, Automate, Personalize, and Brand Kit, enabling you to retrieve and analyze metrics in a structured and scalable way.

With the Analytics APIs, you can access detailed information such as API usage, status codes, cache performance, SDK activity, and device distribution. This allows developers and administrators to monitor trends, diagnose issues, and integrate analytics data into external systems or custom dashboards.

By exposing these metrics through APIs, Contentstack empowers you to move beyond the default dashboard and build tailored monitoring and reporting workflows. Whether you are tracking performance anomalies, optimizing resource allocation, or automating alerts, the Analytics APIs enable data-driven decision-making with real-time and historical insights.

NoteThese endpoints require an organization role with analytics read access, which the Owner and Admin roles have by default. Requests from users without it return a 403 error.

The v2 analytics APIs fetch data asynchronously. All requests, except Retrieve Data, under this section will return a jobId value in the response. You must use this jobId to fetch the actual data using the Retrieve Data endpoint.

NoteThe Analytics API does not support Cross-Origin Resource Sharing (CORS) for browser-based clients. Requests made directly from frontend JavaScript will fail preflight checks and return a CORS error. This API is intended for server-side (server-to-server) consumption only route requests through a backend service or proxy that holds your credentials, rather than calling the endpoint directly from client-side code.

Contentstack uses the authtoken or OAuth token, API key, and Organization ID to make Analytics API requests.

Authtokens are user-specific tokens generated when user logs in to Contentstack. To retrieve the authtoken, log in to your Contentstack account by using the "Log in to your account" request. This request will return the authtoken in the response body.

You can generate multiple authtokens by executing the "Log in to your account" request multiple times. These tokens do not have an expiration time limit. However, currently, there is a maximum limit of 20 valid tokens that a user can use per account at a time, to execute Analytics requests. If you already have valid 20 tokens, creating a new authtoken will automatically cause the oldest authtoken to expire without warning.

For SSO-enabled organizations, the "Log in to your account" request will not return the user authtoken for users who access the organization through Identity Provider login credentials. Consequently, any requests that require user authtoken will not work. Only the owner of the organization and users with permission to access the organization without SSO can use the Analytics APIs. Learn more about REST API Usage.

TipAn alternate way to retrieve the authtoken is via Inspect element. If you are logged in through your browser, right-click and select Inspect or press “F12” to open developer tools, and select the Network tab.

Machine-to-Machine (M2M) apps are designed for secure server-to-server communication, eliminating the need for user intervention. These apps use the OAuth 2.0 protocol for authentication and authorization, making them highly secure and reliable for machine-to-machine interactions. Refer to our guide on Machine-to-Machine Apps for more information.

NoteThe M2M app is currently in Beta. Reach out to our support team to enable it for your organization.

To retrieve the stack API key, perform the steps given below:

1. Go to your stack.
2. Navigate to Settings > Stack.
3. On the right-hand side of the page, under API Credentials, you will get the API Key of your stack.

NoteOnly the developers, admins, and stack owners can view the API key.

To retrieve the organization ID, perform the steps given below:

1. Navigate to Administration through “App Switcher”.
2. By default the Org Info tab opens up, showing the organization name and UID.

Rate limit is the maximum number of requests you can make using Contentstack’s API in a given time period.

By default, the Analytics API enforces 10 GET requests per second per organization.

Your application will receive the HTTP 429 response code if the requests for a given time period exceed the defined rate limits.

To get the current rate limit status, you can check the returned HTTP headers of any API request. These rate limits are reset at the start of each time period.

• The base URL for Analytics API for different regions can be found in the Base URL section.
• URL paths are written in lower case.
• Query parameters and JSON fields use lower case, with underscores (_) separating words.
• The success/failure status of an operation is determined by the HTTP status it returns. Additional information is included in the HTTP response body.
• The JSON number type is bounded to a signed 32-bit integer.

If there is something wrong with the API request, Contentstack returns an error.

Contentstack uses conventional, standard HTTP status codes for errors, and returns a JSON body containing details about the error. In general, codes in the 2xx range signify success. The codes in the 4xx range indicate error, mainly due to information provided (for example, a required parameter or field was omitted). Lastly, codes in the 5xx range mean that there is something wrong with Contentstack’s servers; it is very rare though.

Let’s look at the error code and their meanings.

For the v2 analytics endpoints, how much detail you get depends on the kind of failure:

• If a parameter value is not supported — an unrecognized duration, subService, orderBy or cache value, a malformed date, or an orgUid containing invalid characters — the response is a 400 that names the parameter concerned.
• If the request breaks a rule — a date range longer than 90 days, a date in the future, from later than to, two parameters that cannot be combined, or insufficient permissions — the status code identifies the failure (400, or 403 for permissions) but the body does not describe it, and reads {"message": "An internal server error occurred"}.

NoteDate and parameter-combination rules are checked before the job is created, so a rejected request returns no jobId and there is nothing to retrieve.

NoteThe error codes that we get in the JSON response are not HTTP error codes but are custom Contentstack error codes that are used for internal purposes.

Contentstack offers you a Postman Collection that helps you try out our Analytics API. You can download this collection, connect to your Contentstack account, and try out the Analytics API with ease.

Learn more about how to get started with using the Postman Collection for Contentstack Analytics API.