Analytics APINEW
[API VERSION : 1.0.0]Introduction
Base URL
- US (North America, or NA): https://app.contentstack.com/
- Europe (EU): https://eu-app.contentstack.com/
- Azure North America (Azure NA): https://azure-na-app.contentstack.com/
- Azure Europe (Azure EU): https://azure-eu-app.contentstack.com/
Overview
Note: The Analytics API is currently released as part of an Early Access Program and may not be available to all users. For more information, you can reach out to our support team.
The Product Analytics section provides an overview of how the users of your organization are using Contentstack. The Mission Control section allows developers to access log data (Status Code, Cache Usage, SDK Usages, and Device Usages) of your account and get an overview of your organization’s health.
Note: Only organization owners and admins can access these endpoints.
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.
Authentication
Contentstack uses the authtoken, API key, and Organization ID to make Analytics API requests.
How to Get Authtoken
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 CMA 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 Content Management APIs. Learn more about REST API Usage.
Tip: An 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.
How to Get Stack API Key
To retrieve the stack API key, perform the steps given below:
- Go to your stack.
- Navigate to Settings > Stack.
- On the right-hand side of the page, under API Credentials, you will get the API Key of your stack.
Note: Only the developers, admins, and stack owners can view the API key.
How to Get Organization ID
To retrieve the Organization ID, perform the steps given below:
- Select the Organization from the dropdown on the header and click on the “Org Admin” icon in the left navigation panel.
Or, you can simply click on the “Org Admin” cog beside the Organization that you intend to open. - Click on Info tab to access the section.
Note: Only the organization owners and admins can view the Organization ID.
Rate limiting
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.
| Headers | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of request a client is allowed to make per second per organization. |
| X-RateLimit-Remaining | The number of requests remaining in the current time period. |
API conventions
- 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.
Errors
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.
| HTTP status code | Description |
|---|---|
| 400 Bad Request | The request was incorrect or corrupted. |
| 401 Access Denied | The login credentials are invalid. |
| 403 Forbidden Error | The page or resource that is being accessed is forbidden. |
| 404 Not Found | The requested page or resource could not be found. |
| 412 Pre Condition Failed | The entered API key is invalid. |
| 422 Unprocessable Entity (also includes Validation Error and Unknown Field) | The request is syntactically correct but contains semantic errors. |
| 429 Rate Limit Exceeded | The number of requests exceeds the allowed limit for the given time period. |
| 500 Internal Server Error | The server is malfunctioning and is not specific on what the problem is. |
| 500 Job Failed | The date range for the from and to parameters must be within 90 days. If the range exceeds 90 days, you will receive a 500 Job Failed error response. |
| 502 Bad Gateway Error | A server received an invalid response from another server. |
| 504 Gateway Timeout Error | A server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser. |
Note: The 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.
Using Postman Collection
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 Contenstack Analytics API.
API Reference
Subscription Usage
The Subscription Usage request returns the total number of projects, environments, and domains under Launch within your organization till date. To get the details for CMS and Automate, you can use the Usage Analytics request.
Device Usage
The Device Usage request helps you track the device usage of your customers. You will get a list of servers that your customers are using to access your website/services.
Usage Analytics
The Usage Analytics request gives a quick usage overview of your bandwidth and API utilization over a particular period of time.
- The apiKey cannot be used with the services ["automations", "launch"] simultaneously.
- The apiKey and environmentUid parameters are only applicable to the ["launch"] service.
Top URLs
The Top URLs request gets you the number of requests made from your URLs for the given services.
Status Code
The Status Code request will show the count for the number of API requests made for each HTTP status code. For example, 200, 201, 400, 404, and so on. You can use the httpStatusCode parameter to get the count for a specific status code instead of all status codes.
Cache Usage
The Cache Usage request will show the number of HIT/MISS instances for your cache. Number of HIT indicates that responses were received from the cache and MISS indicates the number of responses retrieved from the database.
SDK Usage
The SDK Usage request gets you the number of requests that were made using the SDKs. It helps you get an overview of the SDK usage by your customers.
Retrieve Data
The Retrieve Data request will take the jobId value that was generated in your response, as a part of its URL and will get you the actual response data for that jobId without any processing delay. Due to the async nature of the APIs, this GET data request acts as an additional step to retrieve your actual response.
- Replace the jobId value in your URL with the jobId value received in your response. For example: {{api_server}}/analytics/v2/job/job_0******9-b**d-4**b-9**0-4**********2/data
- The page parameter is optional. If not provided, the response defaults to page 0. If paginated is true in the response, specify a page number (0, 1, 2, etc.) to get data for that page. An invalid page number will result in an error.
You will receive the response depending on your request and relevant jobId.
