Changelog

Analytics APINEW

[API VERSION : 1.0.0]

Wähle deine Region

Einleitung

Basis 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/
GCP North America (GCP NA): https://gcp-na-app.contentstack.com/

Übersicht

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.

Authentifizierung

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

So erhalten Sie ein 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.

Für SSO-fähige Organisationen gibt die Anforderung „ Einloggen bei Ihrem Konto “ nicht das Benutzerauthentifizierungstoken für Benutzer zurück, die über Anmeldeinformationen des Identitätsanbieters auf die Organisation zugreifen. Folglich funktionieren alle Anfragen, die ein Benutzerauthentifizierungstoken erfordern, nicht. Nur der Eigentümer der Organisation und Benutzer mit der Berechtigung zum Zugriff auf die Organisation ohne SSO können die Inhalt Management APIs verwenden. Mehr erfahren über die REST-API-Nutzung .

Tipp: Sie können das Authtoken auch über das Element „Inspect“ abrufen. Wenn Sie über Ihren Browser angemeldet sind, klicken Sie mit der rechten Maustaste und wählen Sie „Inspect “ oder drücken Sie „F12“, um die Entwicklertools zu öffnen, und wählen Sie die Registerkarte „Netzwerk“ aus.

So erhalten Sie den Stack-API-Schlüssel

Um den Stack-API-Schlüssel abzurufen, führen Sie die folgenden Schritte aus:

Los zu Ihrem Stapel.
Navigieren Sie zu Einstellungen > Stapeln .
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 the “Org Admin” icon in the left navigation panel.
Or, you can simply click the “Org Admin” cog beside the Organization that you intend to open.
Click the Info tab to access the section.

Note: Only Organization owners and admins can view the Organization ID.

Ratenbegrenzung

Das Ratenlimit ist die maximale Anzahl von Anfragen, die Sie über die API von Contentstack in einem bestimmten Zeitraum stellen können.

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

Ihre Anwendung erhält den HTTP-429-Antwortcode, wenn die Anfragen für einen bestimmten Zeitraum die definierten Ratengrenzen überschreiten.

Um den aktuellen Ratenbegrenzungsstatus zu erhalten, können Sie die zurückgegebenen HTTP-Header jeder API-Anfrage überprüfen. Diese Tarifgrenzen werden zu Beginn jedes Zeitraums zurückgesetzt.

Headers	Beschreibung
X-RateLimit-Limit	Die maximale Anzahl von Anfragen, die ein Client pro Sekunde und Organisation stellen darf.
X-RateLimit-Remaining	Die Anzahl der im aktuellen Zeitraum verbleibenden Anforderungen.

API-Konventionen

The base URL for Analytics API for different regions can be found in the Base URL section.
URL Pfade werden in Kleinbuchstaben geschrieben.
Abfrageparameter und JSON-Felder verwenden Kleinbuchstaben, wobei Wörter durch Unterstriche (_) getrennt werden.
Der Erfolgs-/Fehlerstatus einer Operation wird durch den zurückgegebenen HTTP-Status bestimmt. Zusätzliche Informationen sind im HTTP-Antworttext enthalten.
Der JSON-Zahlentyp ist an eine vorzeichenbehaftete 32-Bit-Ganzzahl gebunden.

Fehler

Wenn mit der API-Anfrage etwas nicht stimmt, gibt Contentstack einen Fehler zurück.

Contentstack verwendet herkömmliche, standardmäßige HTTP-Statuscodes für Fehler und gibt einen JSON-Body mit Details zum Fehler zurück. Im Allgemeinen bedeuten Codes im 2xx-Bereich einen Erfolg. Die Codes im 4xx-Bereich weisen auf einen Fehler hin, der hauptsächlich auf die bereitgestellten Informationen zurückzuführen ist (z.B. wurde ein erforderlicher Parameter oder ein Feld ausgelassen). Codes im Bereich 5xx schließlich bedeuten, dass mit den Servern von Contentstack etwas nicht in Ordnung ist; dies ist jedoch sehr selten.

Schauen wir uns den Fehlercode und seine Bedeutung an.

HTTP-Statuscode	Beschreibung
400 Ungültige Anfrage	Die Anfrage war falsch oder beschädigt.
401 Zugriff verweigert	Die Anmeldedaten sind ungültig.
403 Verbotener Fehler	Die Seite oder Ressource, auf die zugegriffen wird, ist verboten.
404 Nicht gefunden	Die angeforderte Seite oder Ressource konnte nicht gefunden werden.
412 Vorbedingung Fehlgeschlagen	Der eingegebene API-Schlüssel ist ungültig.
422 Unprocessable Entity (also includes Validation Error and Unknown Field)	Die Anfrage ist syntaktisch korrekt, enthält jedoch semantische Fehler.
429 Ratenlimit überschritten	Die Anzahl der Anfragen überschreitet das zulässige Limit für den angegebenen Zeitraum.
500 Interner Fehler	Der Server funktioniert nicht richtig und es ist nicht klar, wo das Problem liegt.
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 Ungültiger Gateway Fehler	Ein Server hat eine ungültige Antwort von einem anderen Server erhalten.
200 Job active	The job is still processing. Retry the request after some time to receive the desired response.

Hinweis: Die Fehlercodes, die wir in der JSON-Antwort erhalten, sind keine HTTP-Fehlercodes, sondern benutzerdefinierte Contentstack Fehlercodes, die für interne Zwecke verwendet werden.

Verwendung der 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-Referenz

Abonnementnutzung

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.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "data": [
        {
            "total_launch_project": 9,
            "total_launch_env": 11,
            "total_launch_domain": 2
        }
    ],
    "meta": {
        "orgUid": "blt**************87",
        "from": "2024-06-30",
        "to": "2024-09-12"
    },
    "uid": "0f****46-5ee9-4f38-9146-1f********87"
}

The response body provides an overview of the resources in the Launch section within your organization. Here’s a breakdown of the key elements:

total_launch_project: The total number of projects created within Launch.
total_launch_env: The total number of environments associated with the Launch projects .
total_launch_domain: The total number of domains configured within Launch.

This response gives a clear view of how Launch resources are utilized within the specified date range.

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.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "total": 352,
    "totalDocs": 26,
    "data": [
        {
            "count": 164,
            "type": "cma",
            "device": "sdk contentstack-management-javascript/1.13.0; platform node.js/v18.17.1; os Linux/5.4.176-91.338.amzn2.x86_64;",
            "date": "2024-03-05"
        },
        {
            "count": 62,
            "type": "cma",
            "device": "sdk contentstack-management-javascript/1.13.0; platform node.js/v18.17.1; os Windows/10.0.22000;",
            "date": "2024-02-05"
        },
        {
            "count": 18,
            "type": "cma",
            "device": "sdk contentstack-management-javascript/1.13.0; platform node.js/v18.17.1; os Linux/5.4.176-91.338.amzn2.x86_64;",
            "date": "2024-03-22"
        },
        {
            "count": 16,
            "type": "cma",
            "device": "sdk contentstack-management-javascript/1.13.0; platform node.js/v18.17.1; os Linux/5.4.176-91.338.amzn2.x86_64;",
            "date": "2024-03-04"
        },
        {
            "count": 10,
            "type": "cma",
            "device": "PostmanRuntime/7.37.0",
            "date": "2024-03-20"
        },
        ...
        {
            "date": "2024-03-31"
        }
    ],
    "meta": {
        "orderBy": -1,
        "orgUid": "blt**************87",
        "includeCount": true,
        "from": "2024-01-31",
        "duration": "day",
        "to": "2024-03-31",
        "services": "[\"cdn\",\"cma\"]",
        "skip": 0,
        "limit": 900
    },
    "uid": "35****12-acf4-4ad5-93e0-48********0e"
}

The response body provides detailed insights into customers accessing your website or services. Here’s a breakdown of the key elements:

count: Number of times the specific device was used.
type: The type of access, such as "cma" for Content Management API.
device: Description of the device or software used, including the SDK version, platform, and operating system details.
date: The specific date when the usage was recorded.

This data helps you track and analyze device and environment usage, supporting performance and user experience optimization.

Nutzungsanalyse

The Usage Analytics request gives a quick usage overview of your bandwidth and API utilization over a particular period of time.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "data": [
        {
            "total_api_bandwidth": 0,
            "total_api_count": 0,
            "total_cdn_bandwidth": 0,
            "total_cdn_count": 0,
            "date": "2024-03-02"
        },
        {
            "total_api_bandwidth": 0,
            "total_api_count": 0,
            "total_cdn_bandwidth": 10110,
            "total_cdn_count": 4,
            "date": "2024-02-12"
        },
        {
            "total_api_bandwidth": 0,
            "total_api_count": 0,
            "total_cdn_bandwidth": 0,
            "total_cdn_count": 0,
            "date": "2024-02-22"
        },
        {
            "total_api_bandwidth": 0,
            "total_api_count": 0,
            "total_cdn_bandwidth": 0,
            "total_cdn_count": 0,
            "date": "2024-03-25"
        },
        {
            "total_api_bandwidth": 94685,
            "total_api_count": 26,
            "total_cdn_bandwidth": 0,
            "total_cdn_count": 0,
            "date": "2024-03-04"
        },
        {
            "total_api_bandwidth": 0,
            "total_api_count": 0,
            "total_cdn_bandwidth": 0,
            "total_cdn_count": 0,
            "date": "2024-02-28"
        }
    ],
    "meta": {
        "orgUid": "blt**************87",
        "includeCount": "true",
        "from": "2024-01-31",
        "duration": "day",
        "to": "2024-03-31",
        "services": "[\"cdn\",\"cma\"]"
    },
    "uid": "0f****46-5ee9-4f38-9146-1f********8"
}

The response body provides detailed insights into your organization's API and CDN usage over a specified period. Here’s a breakdown of the key elements:

total_api_bandwidth: The total bandwidth consumed by API requests on the specified date.
total_api_count: The number of API requests executed on the specified date.
total_cdn_bandwidth: The total bandwidth consumed by CDN requests on the specified date.
total_cdn_count: The number of CDN requests made on the specified date.
date: The specific date for the reported statistics.

This data helps monitor and analyze the usage patterns of API and CDN resources, aiding in efficient resource management and planning.

Hinweis

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.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "data": [
        {
            "url": "https://cdn.contentstack.io/v3/content_types?include_count=false",
            "type": "cdn",
            "count": "3"
        },
        {
            "url": "https://cdn.contentstack.io/v3/content_types/header/entries/blt63c1bee28ce24ab1?environment=development",
            "type": "cdn",
            "count": "1"
        },
        {
            "url": "https://cdn.contentstack.io/v3/global_fields",
            "type": "cdn",
            "count": "1"
        },
        {
            "url": "https://cdn.contentstack.io/v3/content_types/test_111222/entries?environment=development",
            "type": "cdn",
            "count": "1"
        }
    ],
    "urlDataSource": "athena",
    "meta": {
        "orgUid": "blt**************87",
        "from": "2024-01-31",
        "duration": "day",
        "to": "2024-03-31",
        "services": "[\"cdn\"]",
        "skip": 0,
        "limit": 900
    },
    "uid": "0f****46-5ee9-4f38-9146-1f********8"
}

The response body provides a detailed summary of the number of requests made to various URLs over a specific period. Here’s a breakdown of the key elements:

url: The specific URL that was accessed.
type: The service type of the URL, such as "cdn".
count: The number of requests made to this URL.

This data helps organizations monitor traffic, identify frequently accessed URLs, and optimize performance.

Statuscode

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.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "data": [
        {
            "count": 63,
            "type": "cma",
            "status": "200",
            "date": "2024-02-05"
        },
        {
            "count": 1,
            "type": "cma",
            "status": "422",
            "date": "2024-03-05"
        },
        {
            "count": 14,
            "type": "cma",
            "status": "200",
            "date": "2024-03-21"
        },
        {
            "count": 10,
            "type": "cma",
            "status": "200",
            "date": "2024-02-15"
        },
        {
            "date": "2024-03-31",
            "count": 0
        }
    ],
    "meta": {
        "from": "2024-01-31",
        "to": "2024-03-31",
        "duration": "day",
        "orgUid": "blt**************87",
        "services": "[\"cdn\",\"cma\"]"
    },
    "uid": "0f****46-5ee9-4f38-9146-1f********8"
}

The response body provides detailed statistics on the number of API requests executed for each HTTP status code over a specified period. Here’s a breakdown of the key elements:

count: The total number of API requests that resulted in the corresponding HTTP status code.
type: The service type (e.g., "cma") that made the requests.
status: The HTTP status code (e.g., "200" for success, "422" for client error).
date: The date on which the requests were executed.

This information helps you monitor the frequency of specific HTTP status codes and track the performance and errors of your API requests.

Cache-Nutzung

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.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "data": [
        {
            "count": 7,
            "type": "cdn",
            "status": "MISS",
            "date": "2024-02-09"
        },
        {
            "count": 1,
            "type": "cdn",
            "status": "HIT",
            "date": "2024-02-08"
        },
        {
            "count": 2,
            "type": "cdn",
            "status": "MISS",
            "date": "2024-02-15"
        },
        {
            "count": 2,
            "type": "cdn",
            "status": "MISS",
            "date": "2024-02-08"
        },
        {
            "count": 4,
            "type": "cdn",
            "status": "MISS",
            "date": "2024-02-12"
        },
        {
            "date": "2024-03-31",
            "count": 0
        }
    ],
    "meta": {
        "orgUid": "blt**************87",
        "includeCount": "true",
        "services": "[\"cdn\",\"cma\"]",
        "from": "2024-01-31",
        "duration": "day",
        "to": "2024-03-31"
    },
    "uid": "0f****46-5ee9-4f38-9146-1f********8"
}

The response body provides insights into how effectively the cache is being utilized for the specified services. Here’s a breakdown of the key elements:

count: The number of instances for the specified cache status (HIT or MISS).
type: The service type (e.g., "cdn") being tracked for cache usage.
status: Indicates whether the cache request was a "HIT" (response received from cache) or "MISS" (response retrieved from the database).
date: The date when the cache status was recorded.

This information helps analyze cache efficiency by detailing the number of HITs and MISSes, aiding in optimizing the cache strategy and understanding cache utilization.

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.

Here’s how your response body would look like when you pass the jobId in the Retrieve Data endpoint.

{
    "total": 16,
    "totalDocs": 4,
    "data": [
        {
            "count": 7,
            "type": "cdn",
            "sdk": "cda-collection/v9.31.0",
            "date": "2024-02-09"
        },
        {
            "count": 4,
            "type": "cdn",
            "sdk": "cda-collection/v9.31.0",
            "date": "2024-02-12"
        },
        {
            "count": 3,
            "type": "cdn",
            "sdk": "cda-collection/v9.31.0",
            "date": "2024-02-08"
        },
        {
            "count": 2,
            "type": "cdn",
            "sdk": "cda-collection/v9.31.0",
            "date": "2024-02-15"
        },
        {
            "date": "2024-02-28"
        }
    ],
    "meta": {
        "orderBy": -1,
        "from": "2024-01-31",
        "to": "2024-02-28",
        "orgUid": "blt**************87",
        "includeCount": true,
        "services": "[\"cdn\",\"cma\"]",
        "duration": "day",
        "skip": 0,
        "limit": 900
    },
    "uid": "0f****46-5ee9-4f38-9146-1f********8"
}

The response body provides detailed insights into how SDKs are being used across different services. Here’s a breakdown of the key elements:

count: The number of requests executed using a specific SDK on a given date.
type: The service type, such as "cdn".
sdk: The SDK version used for the requests.
date: The date when the SDK requests were executed.

This response helps organizations track SDK adoption and effectiveness by revealing usage patterns and frequency.

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.

Hinweis

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.
A 200 Job active response indicates that the job is still processing. Retry the request after some time to receive the desired response body.

You will receive the response depending on your request and relevant jobId.

War dieser Artikel hilfreich?

Contentstack
Grundlagen

Schnellstart
in 5 Minuten

Starter
Apps

Lieferung von Inhalten
APIs

Inhalt
Management APIs

Anleitung
Guides

Contentstack
Grundlagen

Schnellstart
in 5 Minuten

Starter
Apps

Lieferung von Inhalten
APIs

Inhalt
Management APIs

Anleitung
Guides

Analytics APINEW

Einleitung

Basis URL

Übersicht

Authentifizierung

So erhalten Sie ein Authtoken

So erhalten Sie den Stack-API-Schlüssel

How to Get Organization ID

Ratenbegrenzung

API-Konventionen

Fehler

Verwendung der Postman Collection

API-Referenz

Abonnementnutzung

Device Usage

Nutzungsanalyse

Top-URLs

Statuscode

Cache-Nutzung

SDK Usage

Retrieve Data

Contentstack Grundlagen

Schnellstart in 5 Minuten

Starter Apps

Lieferung von Inhalten APIs

Inhalt Management APIs

Anleitung Guides

Contentstack Grundlagen

Schnellstart in 5 Minuten

Starter Apps

Lieferung von Inhalten APIs

Inhalt Management APIs

Anleitung Guides

Analytics APINEW

Einleitung

Basis URL

Übersicht

Authentifizierung

So erhalten Sie ein Authtoken

So erhalten Sie den Stack-API-Schlüssel

How to Get Organization ID

Ratenbegrenzung

API-Konventionen

Fehler

Verwendung der Postman Collection

API-Referenz

Abonnementnutzung

Device Usage

Nutzungsanalyse

Top-URLs

Statuscode

Cache-Nutzung

SDK Usage

Retrieve Data

Contentstack
Grundlagen

Schnellstart
in 5 Minuten

Starter
Apps

Lieferung von Inhalten
APIs

Inhalt
Management APIs

Anleitung
Guides

Contentstack
Grundlagen

Schnellstart
in 5 Minuten

Starter
Apps

Lieferung von Inhalten
APIs

Inhalt
Management APIs

Anleitung
Guides