Reporting API

Our Reporting API is used for extracting data and metrics from your ContentKing account. Typical use-cases include connecting several software solutions together to streamline your reporting tasks and integrating ContentKing in your client portal.

This support article is covering version 2.0 of ContentKing's Reporting API. We recommend using the Reporting API v2.0 for your reporting tasks and integrations as all new endpoints will be only supported on this version.

The legacy Reporting API version is still available. You can find the relevant support documentation here:

Please note that while the legacy Reporting API v1.0 remains available at the moment, it will likely be sunsetted in the future. Therefore we highly recommend using (and migrating to) the Reporting API v2.0.

Reporting API Terms of Use

By using the Reporting API you agree to the Terms of Use.

Retrieving your Reporting API token

To use the Reporting API you need to get your ContentKing account's Reporting API token. You'll find it in the Account section, under the Integration tokens tab (opens in a new tab).

API request headers

When making a request you need to send along the following request headers:

Authorization: token <place-your-API-token-here>
Content-Type: application/json

Note: you need to provide the string "token" followed by a space and your actual API token.

Reporting API URL

ContentKing Reporting API is available on this URL.

https://api.contentkingapp.com/

Retrieving a list of websites in your account

Send the following request to get a list of websites in your account:

GET /v2/entities/websites

The response will look like this:

{
    "data": [
        {
            "id": "1-234",
            "app_url": "https://app.contentkingapp.com/websites/1-234/dashboard",
            "domain": "https://www.contentkingapp.com",
            "name": "null",
            "page_capacity": 1000
        },
        {
            "id": "1-2345",
            "app_url": "https://app.contentkingapp.com/websites/1-2345/dashboard",
            "domain": "https://www.contentkingapp.de",
            "name": "ContentKing - DE",
            "page_capacity": 1000
        },
    ]
}

Data types overview for this endpoint

Property Data Type
"id" string
"app_url" string (absolute URL)
"domain" string (absolute URL)
"name" string
"page_capacity" integer

Retrieving a list of segments for a website

Send the following request to get a list of segments for a specific website in your account:

GET /v2/entities/segments?website_id=<website_id>

The response will look like this:

{
    "data": [
        {
            "id": "1",
            "color": "bf86d5",
            "label": "Important pages",
            "shortcode": null
        },
        {
            "id": "2",
            "color": "72c035",
            "label": "Indexable",
            "shortcode": null
        },
    ]
}

Data types overview for this endpoint

Property Data Type
"id" string
"color" string
"label" string
"shortcode" string

Retrieving statistics for a website or website's segment

Send the following request to get statistics for a specific website in your account:

GET /v2/data/statistics?website_id=<website_id>&scope=website

Send the following request to get statistics for a specific segment within the website using the segment ID:

GET /v2/data/statistics?website_id=<website_id>&scope=segment:<segment_id>

Send the following request to get statistics for a specific segment within the website using the segment’s label:

GET /v2/data/statistics?website_id=<website_id>&scope=segment_label:<segment_label>

The response will look like this:

{
    "data": {
        "health": 916,
        "number_of_issues": 1234,
        "number_of_urls": {
            "missing": 0,
            "page": 123,
            "redirect": 0,
            "server_error": 0,
            "unreachable": 0
        },
        ": {
            "h1": {
                "available": 123,
                "empty": 0,
                "missing": 0
            },
            "health": {
                "0-100": 0,
                "100-200": 0,
                "200-300": 0,
                "300-400": 0,
                "400-500": 0,
                "500-600": 0,
                "600-700": 0,
                "700-800": 0,
                "800-900": 0,
                "900-1000": 1234
            },
            "hreflang_language": {
                "en": 1234,
                "missing": 0,
                "others": 0
            },
            "is_disallowed_in_robots_txt": {
                "true": 0,
                "false": 1234
            },
            "is_in_sitemap": {
                "true": 1234,
                "false": 0
            },
            "is_indexable": {
                "true": 1234,
                "false": 0
            },
            "is_indexable_due_to_meta_robots": {
                "no": 0,
                "not_applicable": 0,
                "yes": 1234
            },
            "is_indexable_due_to_x_robots_tag": {
                "no": 0,
                "not_applicable": 0,
                "yes": 1234
            },
            "is_linked": {
                "true": 1234,
                "false": 0
            },
            "meta_description": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "open_graph_description": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "open_graph_image": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "open_graph_title": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "open_graph_type": {
                "empty": 0,
                "missing": 0,
                "others": 0,
                "values": {
                    "article": 1230,
                    "website": 2,
                    "object": 2
                }
            },
            "open_graph_url": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "importance": {
                "0-1": 0,
                "1-2": 0,
                "2-3": 0,
                "3-4": 109,
                "4-5": 109,
                "5-6": 103,
                "6-7": 43,
                "7-8": 28,
                "8-9": 16,
                "9-10": 800
            },
            "status_code": {
                "200": 1234
            },
            "title": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "twitter_card": {
                "empty": 0,
                "missing": 0,
                "others": 0,
                "values": {
                    "summary_large_image": 1234
                }
            },
            "twitter_description": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "twitter_image": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "twitter_site": {
                "empty": 0,
                "missing": 0,
                "others": 0,
                "values": {
                    "@contentking": 1234
                }
            },
            "twitter_title": {
                "available": 1234,
                "empty": 0,
                "missing": 0
            },
            "is_https": {
                "true": 1234,
                "false": 0
            },
            "url_depth": {
                "0": 1,
                "1": 15,
                "2": 399,
                "3": 29,
                "4": 1000,
                "5": 0,
                "6": 0,
                "7": 0,
                "8": 0,
                "9": 0,
                "10+": 0
            },
            "domain": {
                "www.contentkingapp.de": 1234
            },
            "lighthouse_cls": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            },
            "lighthouse_fcp": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            },
            "lighthouse_lcp": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            },
            "lighthouse_performance": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            },
            "lighthouse_si": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            },
            "lighthouse_tbt": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            },
            "lighthouse_tti": {
                "good": 1234,
                "needsImprovement": 0,
                "bad": 0
            }
        }
    },
    "data_captured_at": "2022-08-04T15:23:01+02:00",
    "is_data_golden": false
}

Data types overview for this endpoint

Property Data Type
"health" integer
"number_of_issues" integer
"number_of_urls" array
"number_of_urls.page" integer
"number_of_urls.missing" integer
"number_of_urls.redirect" integer
"number_of_urls.server_error" integer
"number_of_urls.unreachable" integer
"number_of_urls_per_property array
"h1" array
"h1.available" integer
"h1.empty" integer
"h1.missing" integer
"health" array
"health.0-100" integer
"health.100-200" integer
"health.200-300" integer
"health.300-400" integer
"health.400-500" integer
"health.600-700" integer
"health.800-900" integer
"health.900-1000" integer
"hreflang_language" array
"hreflang_language.hreflang_attribute" string (depending on the website's implementation)
"hreflang_language.missing" integer
"hreflang_language.other" integer
"is_disallowed_in_robots_txt" array
"is_disallowed_in_robots_txt.true" integer
"is_disallowed_in_robots_txt.false" integer
"is_in_sitemap" array
"is_in_sitemap.true" integer
"is_in_sitemap.false" integer
"is_indexable" array
"is_indexable.true" integer
"is_indexable.false" integer
"is_indexable_due_to_meta_robots" array
"is_indexable_due_to_meta_robots.no" integer
"is_indexable_due_to_meta_robots.not_applicable" integer
"is_indexable_due_to_meta_robots.yes" integer
"is_indexable_due_to_x_robots_tag" array
"is_indexable_due_to_x_robots_tag.no" integer
"is_linked" array
"is_linked.true" integer
"is_linked.false" integer
"meta_description" array
"meta_description.available" integer
"meta_description.empty" integer
"meta_description.missing" integer
"open_graph_description" array
"open_graph_description.available" integer
"open_graph_description.empty" integer
"open_graph_description.missing" integer
"open_graph_image" array
"open_graph_image.available" integer
"open_graph_image.empty" integer
"open_graph_image.missing" integer
"open_graph_title" array
"open_graph_title.available" integer
"open_graph_title.empty" integer
"open_graph_title.missing" integer
"open_graph_type" array
"open_graph_type.empty" integer
"open_graph_type.missing" integer
"open_graph_type.others" integer
"open_graph_type.values" array
"open_graph_type.values.name" integer
"open_graph_URL" array
"open_graph_URL.available" integer
"open_graph_URL.empty" integer
"open_graph_URL.missing" integer
"importance" array
"importance.0-1" integer
"importance.1-2" integer
"importance.2-3" integer
"importance.3-4" integer
"importance.4-5" integer
"importance.6-7" integer
"importance.8-9" integer
"importance.9-1" integer
"status_code" array
"status_code.value" integer
"title" array
"title.available" integer
"title.empty" integer
"title.missing" integer
"twitter_card" array
"twitter_card.empty" integer
"twitter_card.missing" integer
"twitter_card.others" integer
"twitter_card.values" array
"twitter_card.values_name" integer
"twitter_description" array
"twitter_description.available" integer
"twitter_description.empty" integer
"twitter_description.missing" integer
"twitter_image" array
"twitter_image.available" integer
"twitter_image.empty" integer
"twitter_image.missing" integer
"twitter_site" array
"twitter_site.empty" integer
"twitter_site.missing" integer
"twitter_site.others" integer
"twitter_site.values" array
"twitter_site.values.name" integer
"twitter_title" array
"twitter_title.available" integer
"twitter_title.empty" integer
"twitter_title.missing" integer
"is_https" array
"is_https.true" boolean
"is_https.false" boolean
"url_depth" array
"url_depth.0" integer
"url.depth.1" integer
"url.depth.2" integer
"url.depth.3" integer
"url.depth.4" integer
"url.depth.6” integer
"url.depth.7" integer
"url.depth.8" integer
"url.depth.9" integer
"url.depth.10+" integer
"domain" array
"domain_name" string
"data_captured_at" datetime (ISO-8601 format)
"is_data_golden" boolean

Specific errors when requesting statistics

404 Not found
{
    "error": "No statistics found for given scope"
}

This response means that the statistics for the given scope (website or segment) are not available at this time. They may or may not become available at a later time, depending on the actual content of the scope.

Retrieving list of pages for a website

Send the following request to get a list of pages for a specific website:

GET /v2/data/pages?website_id=<website_id>&page=1&per_page=100&sort=url&direction=desc

Send the following request to get a list of pages for a specific segment within the website using the segment ID:

GET /v2/data/pages?website_id=<website_id>&page=1&per_page=100&sort=url&direction=desc&scope=segment:<segment_id>

Send the following request to get a list of pages for a specific segment within the website using the segment's label:

GET /v2/data/pages?website_id=<website_id>&page=1&per_page=100&sort=url&direction=desc&scope=segment_label:<segment_label>

Pagination

Query parameters per_page and page are used for iterating over large result sets.

  • per_page can be in range from 1 to 500
  • page can be 1 up to ceil(total / per_page). If page is higher than max value the urls field will be an empty array

Response

Each API response contains 2 main keys:

  • total count of urls in result set for given query
  • urls paginated urls based on query parameters per_page and page
{
    "data": {
        "total": 1,
        "urls": [
            {
                "aa_average_time_spent_on_site": null,
                "aa_bounce_rate": null,
                "aa_page_views": null,
                "aa_revenue": null,
                "aa_unique_visitors": null,
                "analytics_services": [
                    "google_analytics"
                ],
                "app_url": "https://app.contentkingapp.com/websites/1-2345/pages/123456",
                "canonical": null,
                "canonical_type": "none",
                "custom_elements": [],
                "ga_average_time": null,
                "ga_bounce_rate": null,
                "ga_page_value": null,
                "ga_page_views": null,
                "ga_unique_page_views": null,
                "ga_v4_active_users": null,
                "ga_v4_average_engagement_time": null,
                "ga_v4_engagement_rate": null,
                "ga_v4_screen_page_views": null,
                "ga_v4_total_revenue": null,
                "gsc_clicks": null,
                "gsc_ctr": null,
                "gsc_impressions": null,
                "gsc_position": null,
                "h1": "null",
                "health": 920,
                "hreflang_language": null,
                "is_disallowed_in_robots_txt": false,
                "is_https": false,
                "is_in_sitemap": false,
                "is_indexable": false,
                "is_indexable_due_to_meta_robots": false,
                "is_indexable_due_to_x_robots_tag": true,
                "is_linked": true,
                "lfa_bing_desktop_frequency": null,
                "lfa_bing_desktop_last_visit": null,
                "lfa_bing_frequency": null,
                "lfa_bing_last_visit": null,
                "lfa_bing_mobile_frequency": null,
                "lfa_bing_mobile_last_visit": null,
                "lfa_google_desktop_frequency": null,
                "lfa_google_desktop_last_visit": null,
                "lfa_google_frequency": null,
                "lfa_google_last_visit": null,
                "lfa_google_mobile_frequency": null,
                "lfa_google_mobile_last_visit": null,
                "lighthouse_cls": null,
                "lighthouse_fcp": null,
                "lighthouse_lcp": null,
                "lighthouse_performance": null,
                "lighthouse_si": null,
                "lighthouse_tbt": null,
                "lighthouse_tti": null,
                "link_amp": null,
                "link_next": null,
                "link_prev": null,
                "meta_description": "null",
                "mobile_variant": null,
                "number_of_hreflangs": 0,
                "number_of_incoming_internal_canonicals": 0,
                "number_of_incoming_internal_links": 0,
                "number_of_incoming_internal_redirects": 0,
                "number_of_outgoing_external_links": 5,
                "number_of_outgoing_internal_links": 147,
                "open_graph_description": null,
                "open_graph_image": null,
                "open_graph_title": null,
                "open_graph_type": null,
                "open_graph_url": null,
                "redirect": null,
                "relevance": 3,
                "schema_org_number_of_types": 0,
                "schema_org_types": [],
                "segments": [],
                "status_code": 200,
                "tag_managers": null,
                "time_document_download": 12,
                "title": "null",
                "twitter_card": null,
                "twitter_description": null,
                "twitter_image": null,
                "twitter_site": null,
                "twitter_title": null,
                "type": "page",
                "url": "https://www.contentkingapp.com/
                "url_path": "/",
                "visual_analytics_services": null
            }
        ]
    },
    "data_captured_at": "2022-08-16T11:24:27+02:00",
    "is_data_golden": false
}

Data types overview for this endpoint

Property Data Type
"urls" array
"urls.aa_average_time_spent_on_site" integer (seconds)
"urls.aa_bounce_rate" float (percentage)
"urls.aa_page_views" integer
"urls.aa_unique_visitors" integer
"urls.aa_revenue" float
"urls.analytics_services" string
"urls.app_url" string
"urls.canonical" string
"urls.canonical_type" string
"urls.custom_elements" array
"urls.custom_elements.custom_element_name" string/number/boolean/date (depending on configuration)
"urls.ga_average_time" integer (seconds)
"urls.ga_bounce_rate" float (percentage)
"urls.ga_page_views" integer
"urls.ga_unique_page_views" integer
"urls.ga_page_value" float
"urls.ga_v4_active_users" integer
"urls.ga_v4_average_engagement_time" integer (seconds)
"urls.ga_v4_engagement_rate" float (percentage)
"urls.ga_v4_screen_page_views" integer
"urls.ga_v4_total_revenue" float
"urls.gsc_clicks" integer
"urls.gsc_impressions" integer
"urls.gsc_ctr" float (percentage)
"urls.gsc_position" float
"urls.gsc_date_range" array
"urls.gsc_date_range.since" date (YYYY-MM-DD)
"urls.gsc_date_range.until" date (YYYY-MM-DD)
"urls.health" number
"urls.hreflang_language" string
"urls.is_disallowed_in_robots_txt" boolean
"urls.is_https" boolean
"urls.is_in_sitemap" boolean
"urls.is_indexable" boolean
"urls.is_indexable_due_to_meta_robots" boolean
"urls.is_indexable_due_to_x_robots_tag" boolean
"urls.is_linked" boolean
"urls.legacy_id_fallback" string
"urls.lfa_bing_desktop_last_visit" string,
"urls.lfa_bing_last_visit string,
"urls.lfa_bing_mobile_frequency" string,
"urls.lfa_bing_mobile_last_visit" string,
"urls.lfa_google_desktop_frequency" string,
"urls.lfa_google_desktop_last_visit" string,
"urls.lfa_google_last_visit" string,
"urls.lfa_google_last_visit string,
"urls.lfa_google_mobile_frequency" string,
"urls.lfa_google_mobile_last_visit" string,
"urls.lighthouse_performance" array
"urls.lighthouse_performance.value" integer
"urls.lighthouse_performance.range" string
"urls.lighthouse_cls" array
"urls.lighthouse_cls.value" float
"urls.lighthouse_cls.range" string
"urls.lighthouse_fcp" array
"urls.lighthouse_fcp.value" integer (miliseconds)
"urls.lighthouse_fcp.range" string
"urls.lighthouse_lcp" array
"urls.lighthouse_lcp.value" integer (miliseconds)
"urls.lighthouse_lcp.range" string
"urls.lighthouse_si" array
"urls.lighthouse_si.value" integer (miliseconds)
"urls.lighthouse_si.range" string
"urls.lighthouse_tbt" array
"urls.lighthouse_tbt.value" integer (miliseconds)
"urls.lighthouse_tbt.range" string
"urls.lighthouse_tti" array
"urls.lighthouse_tti.value" integer (miliseconds)
"urls.lighthouse_tti.range" string
"urls.link_amp" string (absolute URL)
"urls.link_next" string (absolute URL)
"urls.link_prev" string (absolute URL)
"urls.mobile_variant" string (absolute URL)
"urls.number_of_hreflangs" integer
"urls.number_of_incoming_internal_canonicals" integer
"urls.number_of_incoming_internal_links" integer
"urls.number_of_incoming_internal_redirects" integer
"urls.number_of_outgoing_internal_links" integer
"urls.number_of_outgoing_external_links" integer
"urls.title" string
"urls.meta_description" string
"urls.h1" string
"urls.open_graph_title" string
"urls.open_graph_description" string
"urls.open_graph_image" string (absolute URL)
"urls.open_graph_url" string (absolute URL)
"urls.open_graph_type" string
"urls.twitter_card" string
"urls.twitter_title" string
"urls.twitter_description" string
"urls.twitter_image" string (absolute URL)
"urls.twitter_site" string
"urls.redirect string
"urls.relevance float
"urls.schema_org_number_of_types" integer
"urls.schema_org_types" array of strings
"urls.segments" array of strings (containing Segment IDs, see Retrieving a list of segments)
"urls.status_code" integer
"urls.tag_managers" string
"urls.time_document_download" number
"urls.type" string
"urls.url" string (absolute URL)
"urls.url_path" string (relative URL)
"urls.visual_analytics_services" string
"data_captured_at" datetime (ISO-8601 format)
"is_data_golden" boolean

Retrieving data for a specific page within a website

Send the following request to get data for a specific page within a website in your account:

/v2/data/page?website_id=<website_id>&url=<url>

Response for a page

The response for an existing page (URL returns HTTP status 200) will look like this:

{
    "data": {
        "url": "https://www.contentkingapp.com/",
        "url_unique_id": "1-234",
        "is_https": true,
        "ga_v4_active_users": 10,
        "ga_v4_average_engagement_time": 10,
        "ga_v4_date_range": {
            "since": "2022-05-16",
            "until": "2022-08-14"
        },
        "ga_v4_engagement_rate": 10,
        "ga_v4_screen_page_views": 10,
        "ga_v4_total_revenue": 10,
        "gsc_clicks": 10,
        "gsc_ctr": 10,
        "gsc_date_range": {
            "since": "2022-05-16",
            "until": "2022-08-14"
        },
        "gsc_impressions": 10,
        "gsc_position": 10,
        "health": 881,
        "is_disallowed_in_robots_txt": false,
        "is_indexable": true,
        "is_indexable_due_to_meta_robots": "yes",
        "is_indexable_due_to_x_robots_tag": "yes",
        "is_in_sitemap": true,
        "lighthouse_cls": {
            "value": 0,
            "range": "good"
        },
        "lighthouse_fcp": {
            "value": 1000,
            "range": "good"
        },
        "lighthouse_lcp": {
            "value": 2000,
            "range": "good"
        },
        "lighthouse_performance": {
            "value": 95,
            "range": "good"
        },
        "lighthouse_si": {
            "value": 3700,
            "range": "needsImprovement"
        },
        "lighthouse_tbt": {
            "value": 669,
            "range": "bad"
        },
        "lighthouse_tti": {
            "value": 2000,
            "range": "good"
        },
        "relevance": 9.33,
        "status_code": 200,
        "type": "page",
        },
        "content": [
            {
                "type": "canonical",
                "content": "null"
            {
                "type": "link_alternate_hreflang",
                "content": "null",
                "hreflang": "en"
            },
            {
                "type": "link_alternate_hreflang",
                "content": "null",
                "hreflang": "x-default"
            },
            {
                "type": "title",
                "content": "Some Title"
            },
            {
                "type": "meta_description",
                "content": "Some Meta Description"
            },
            {
                "type": "h1",
                "content": "null"
            },
            },
            {
                "type": "open_graph_description",
                "content": "null"
            },
            {
                "type": "open_graph_image",
                "content": "null"
            },
            {
                "type": "open_graph_title",
                "content": "null"
            },
            {
                "type": "open_graph_type",
                "content": "null"
            },
            {
                "type": "open_graph_url",
                "content": "null"
            },
            {
                "type": "twitter_card",
                "content": "null"
            },
            {
                "type": "twitter_site",
                "content": "null"
            },
            {
                "type": "twitter_title",
                "content": "null"
            },
            {
                "type": "twitter_description",
                "content": "null"
            },
            {
                "type": "twitter_image",
                "content": "null"
            },
            {
                "type": "google_analytics",
                "content": "UA-12345678-1"
            },
            {
                "type": "google_tag_manager",
                "content": "GTM-AB12345"
            }
        ],
        "schema_org": [],
        "segments": [
            "1111111",
        ],
        "app_url": "https://app.contentkingapp.com/websites/1-12345/pages/123456789",
        "time_document_download": "123",
        "open_issues": [
            {
                "name": "analytics/visual_analytics_missing"
            },
            {
                "name": "open_graph/description_incorrect_length"
            },
            {
                "name": "open_graph/title_incorrect_length"
            },
        ],
        "custom_elements": {}
        "unstable_last_checked_at": "2022-08-15T13:32:12+02:00"
    },
    "data_captured_at": "2022-08-15T13:32:29+02:00",
    "is_data_golden": false
}

Response for a redirect

The response for a redirect (URL returns HTTP status 3xx) will look like this:

{
    "data": {
        "url": "https://contentkingapp.com/",
        "url_unique_id": "123345",
        "is_https": true,
        "is_disallowed_in_robots_txt": false,
        "is_indexable": false,
        "is_indexable_due_to_meta_robots": "not_applicable",
        "is_indexable_due_to_x_robots_tag": "not_applicable",
        "is_in_sitemap": false,
        "redirect": {
            "location": "https://www.contentkingapp.com/",
            "url": "https://www.contentkingapp.com/"
        },
        "status_code": 301,
        "type": "redirect",
        "enrichment_fields_data": {},
        "segments": [],
        "app_url": "https://app.contentkingapp.com/websites/5-2457491/pages/12334563485638745638465837465836",
        "time_document_download": 123,
        "unstable_last_checked_at": "2022-08-15T06:28:42+02:00"
    },
    "data_captured_at": "2022-08-15T13:55:35+02:00",
    "is_data_golden": false
}

Response for missing

The response for a missing page (URL returns HTTP status 4xx) will look like this:

{
    "data": {
        "url": "https://www.contentkingapp.com/blog/contentking/",
        "url_unique_id": "a1246718246817264871624871628471",
        "is_https": true,
        "ga_v4_active_users": 0,
        "ga_v4_average_engagement_time": 0,
        "ga_v4_date_range": {
            "since": "2022-02-21",
            "until": "2022-05-22"
        },
        "ga_v4_engagement_rate": 0,
        "ga_v4_screen_page_views": 0,
        "ga_v4_total_revenue": 0,
        "gsc_clicks": 0,
        "gsc_ctr": 0,
        "gsc_date_range": {
            "since": "2022-02-21",
            "until": "2022-05-22"
        },
        "gsc_impressions": 0,
        "gsc_position": 0,
        "is_disallowed_in_robots_txt": false,
        "is_indexable": false,
        "is_indexable_due_to_meta_robots": "not_applicable",
        "is_indexable_due_to_x_robots_tag": "not_applicable",
        "is_in_sitemap": false,
        "status_code": 404,
        "type": "missing",
        "enrichment_fields_data": {},
        "segments": [],
        "app_url": "https://app.contentkingapp.com/websites/5-2457491/pages/a1246718246817264871624871628471",
        "time_document_download": 206,
        "unstable_last_checked_at": "2022-08-15T09:56:17+02:00"
    },
    "data_captured_at": "2022-08-15T14:31:25+02:00",
    "is_data_golden": false
}

Data types overview for this endpoint

Property Data Type
"url" string (absolute URL)
"is_https" boolean
"ga_average_time" integer (seconds)
"ga_bounce_rate" float (percentage)
"ga_page_views" integer
"ga_unique_page_views" integer
"ga_page_value" float
"ga_date_range" array
"ga_date_range.since" date (YYYY-MM-DD)
"ga_date_range.until" date (YYYY-MM-DD)
"ga_v4_active_users" integer
"ga_v4_average_engagement_time" integer (seconds)
"ga_v4_engagement_rate" float (percentage)
"ga_v4_screen_page_views" integer
"ga_v4_total_revenue" float
"ga_v4_date_range" array
"ga_v4_date_range.since" date (YYYY-MM-DD)
"ga_v4_date_range.until" date (YYYY-MM-DD)
"gsc_clicks" integer
"gsc_impressions" integer
"gsc_ctr" float (percentage)
"gsc_position" float
"gsc_date_range" array
"gsc_date_range.since" date (YYYY-MM-DD)
"gsc_date_range.until" date (YYYY-MM-DD)
"health" number
"relevance" float
"is_disallowed_in_robots_txt" boolean
"is_indexable" boolean
"is_indexable_due_to_meta_robots" boolean
"is_indexable_due_to_x_robots_tag" boolean
"is_in_sitemap" boolean
"status_code" integer
"time_document_download" number
"type" string
"content" array
"content.type" string
"content.content" string
"custom_elements" array
"custom_elements.custom_element_name" string/number/boolean/date (depending on configuration)
"schema_org" array (containing different Schema properties as defined by schema.org (opens in a new tab))
"segments" array of strings (containing Segment IDs, see Retrieving a list of segments)
"app_url" string (absolute URL)
"open_issues" array
"open_issues.name" string (see List of issues)
"lighthouse_performance" array
"lighthouse_performance.value" integer
"lighthouse_performance.range" string
"lighthouse_cls" array
"lighthouse_cls.value" float
"lighthouse_cls.range" string
"lighthouse_fcp" array
"lighthouse_fcp.value" integer (miliseconds)
"lighthouse_fcp.range" string
"lighthouse_lcp" array
"lighthouse_lcp.value" integer (miliseconds)
"lighthouse_lcp.range" string
"lighthouse_si" array
"lighthouse_si.value" integer (miliseconds)
"lighthouse_si.range" string
"lighthouse_tbt" array
"lighthouse_tbt.value" integer (miliseconds)
"lighthouse_tbt.range" string
"lighthouse_tti" array
"lighthouse_tti.value" integer (miliseconds)
"lighthouse_tti.range" string
"unstable_last_checked_at" datetime (ISO-8601 format)
"data_captured_at" datetime (ISO-8601 format)
"is_data_golden" boolean

Specific errors when requesting page data

404 Not found
{
    "error": "Requested URL was not found"
}

This response means that the URL passed in the request is not monitored by ContentKing.

404 Not found
{
    "error": "Requested URL cannot be provided via Reporting API"
}

This response means that data for the URL passed in the request is not available via the Reporting API.

Retrieving a list of alerts for a website

Send the following request to get a list of alerts for a specific website in your account:

GET /v2/alerts?website_id=<website_id>

The response will look like this:

{
    "data": [
        {
            "id": "1",
            "app_url": "https://app.contentkingapp.com/websites/1-234/alerts?alert=1",
            "date_last_updated": "2022-08-04T13:40:50+02:00",
            "date_opened": "2022-07-27T09:34:44+02:00",
            "scope": "website",
            "type": "content_change.meta_description"
        },
        {
            "id": "2",
            "app_url": "https://app.contentkingapp.com/websites/1-234/alerts?alert=2",
            "date_last_updated": "2022-08-04T13:40:50+02:00",
            "date_opened": "2022-07-26T07:03:25+02:00",
            "scope": "website",
            "type": "pages_became_non_indexable"
        }
    ]
}

Data types overview for this endpoint

Property Data Type
"id" string
"app_url" string (absolute URL)
"date_last_updated" datetime (ISO 8601 format)
"date_opened" datetime (ISO 8601 format)
"scope" string
"type" string

Retrieving list of pages for a website alert

Send the following request to get a list of pages for a specific website alert:

GET /v2/alerts/alert_pages?website_id=<website_id>&alert_id=<alert_id>&page=1&per_page=100

The response will look like this:

{
    "data": {
        "total": 1,
        "urls": [
            {
                "app_url": "https://app.contentkingapp.com/websites/1-2/pages/3",
                "relevance": 6.05,
                "segments": [],
                "status": "entered",
                "url": "https://www.contentkingapp.com/",
            },
        ]
    }
}

Data types overview for this endpoint

Property Data Type
"total" integer
"urls" array
"urls.app_url" string (absolute URL)
"urls.relevance" float
"segments" array of strings (containing Segment IDs, see Retrieving a list of segments)
"status" string
"urls.url" string (absolute URL)

Retrieving a list of issues for a website or segment

Send the following request to get a list of issues for a specific website in your account:

GET /v2/data/issues?website_id=<website_id>

It is also possible to retrieve a list of issues for a specific segment based on the segment ID or label.

Send the following request to get a list of issues for a specific segment within the website using the segment ID:

GET /v2/data/issues?website_id=<website_id>&scope=segment:<segment_id>

Send the following request to get a list of issues for a specific segment within the website using the segment’s label:

GET /v2/data/issues?website_id=<website_id>&scope=segment_label:<segment_label>

The response will look like this:

{
    "data": [
        {
            "name": "analytics/analytics_missing",
            "points_gained": 79,
            "points_to_gain": 0,
            "scope": "pages",
            "pages_per_issue_state": {
                "absolute_number": {
                    "open": 0,
                    "closed": 0,
                    "ignored": 527,
                    "not_applicable": 0,
                    "not_required": 0,
                    "unknown": 0
                },
                "percentage": {
                    "open": 0,
                    "closed": 0,
                    "ignored": 100,
                    "not_applicable": 0,
                    "not_required": 0,
                    "unknown": 0
                }
            }
        },
    ],
    "data_captured_at": "2022-08-04T14:03:19+02:00",
    "is_data_golden": false
}

Data types overview for this endpoint

Property Data Type
"name" string
"points_gained" integer
"points_to_gain" integer
"scope" string
"pages_per_issue_state" array
"pages_per_issue_state.open" integer
"pages_per_issue_state.closed" integer
”pages_per_issue_state.ignored" integer
"pages_per_issue_state.not_applicable" integer
"pages_per_issue_state.unknown" integer
"percentage" array
"percentage.open" integer
"percentage.closed" integer
”percentage.ignored" integer
"percentage.not_applicable" integer
"percentage.unknown" integer
"data_captured_at" datetime (ISO-8601 format)
"is_data_golden" boolean

Retrieving list of pages for a website issue

Send the following request to get list of pages for a specific website issue:

GET /v2/data/affected_pages?website_id=<website_id>&issue=<issue>&page=1&per_page=100

The response will look like this:

{
    "data": {
        "total": 1,
        "urls": [
            {
                "app_url": "https://app.contentkingapp.com/websites/1-123455/pages/123455678",
                "relevance": 9.33,
                "segments": [
                    "88611",
                ],
                "url": "https://www.contentkingapp.com/",
                "url_path": "/"
            },
        ]    
    },
    "data_captured_at": "2022-08-16T12:42:35+02:00", 
    "is_data_golden": false
}
Property Data Type
"total" integer
"urls" array
"urls.app_url" string (absolute URL)
"urls.relevance" float
"segments" array of strings (containing Segment IDs, see Retrieving a list of segments)
"urls.url" string (absolute URL)
"urls.path" string (absolute URL)
"data_captured_at" datetime (ISO-8601 format)
"is_data_golden" boolean

List of issues

Issue Description
Analytics  
analytics/analytics_missing No analytics installed
analytics/visual_analytics_missing No visual analytics installed
Content Headings  
h1/duplicate H1 heading is not unique
h1/incorrect_length H1 heading has incorrect length
h1/missing H1 heading is missing
h1/too_many More than one H1 heading
Canonical Link  
canonical_link/incorrectly_canonicalized Canonical link to other page present on non-indexable page
canonical_link/missing Canonical link is missing
canonical_link/points_to_unindexable Canonical link is pointing to non-indexable page
canonical_link/too_many More than one canonical link
Images  
images/alt_attribute Images are missing alt-attribute
Links  
links/broken Page contains broken links
links/redirected Page contains links to redirects
links/to_canonicalized Page contains links to canonicalized URLs
Meta Information  
meta_description/duplicate Meta description is not unique
meta_description/incorrect_length Meta description has incorrect length
meta_description/missing Meta description is missing
meta_description/too_many There are multiple meta descriptions on the page
title/duplicate Page title is not unique
title/incorrect_length Page title has incorrect length
title/missing Title is missing
title/too_many There are multiple titles on pages
Open Graph  
open_graph/description_incorrect_length Open Graph description has incorrect length
open_graph/description_missing Open Graph description is missing
open_graph/image_missing Open Graph image is missing
open_graph/title_incorrect_length Open Graph title has incorrect length
open_graph/title_missing Open Graph title is missing
open_graph/url_missing Open Graph URL is missing
Twitter Cards  
twitter_cards/description_incorrect_length Twitter Cards description has incorrect length
twitter_cards/description_missing Twitter Cards description is missing
twitter_cards/image_missing Twitter Cards image is missing
twitter_cards/site_missing Twitter Cards site property is missing
twitter_cards/title_incorrect_length Twitter Cards title has incorrect length
twitter_cards/title_missing Twitter Cards title is missing
twitter_cards/type_invalid Twitter Cards type value is not valid
twitter_cards/type_missing Twitter Cards type is not present
XML Sitemap  
xml_sitemap/incorrectly_missing Page is not included in XML sitemap
xml_sitemap/incorrectly_present Pages incorrectly present in XML sitemap
Schema.org  
schema_org/errors Schema.org implementation has an invalid structure
schema_org/invalid_json Schema element with invalid JSON-LD object present
Hreflang  
hreflang/conflicting_targets Hreflang attribute value is pointed to multiple targets
hreflang/invalid_target Invalid hreflang target present
hreflang/invalid_value Invalid hreflang attribute value present
hreflang/missing_self_reference Self-referencing hreflang not present
hreflang/missing_specific_audience Hreflang implementation does not contain any hreflang attribute specifying a language and/or region
hreflang/missing_x_default Hreflang attribute with x-default value is missing
Robot directives  
robot_directives/conflicting Valid robot directives give conflicting directives to search engines
robot_directives/invalid Valid robot directives give conflicting directives to search engines
robot_directives/unsupported Valid but unsupported robot directives to a search engine present
ContentKing Lighthouse Web Vitals  
lighthouse/performance Performance score is too low
lighthouse/fcp First Contentful Paint takes too long
lighthouse/lcp Largest Contentful Paint takes too long
lighthouse/tti Time To Interactive takes too long
lighthouse/si Speed Index is too high
lighthouse/tbt Total Blocking Time is too long
lighthouse/cls Cumulative Layout Shift is too large

Retrieving historical data

Certain endpoints support retrieving historical data using the data_captured_at query parameter.

The data_captured_at parameter is a timestamp indicating when the data was collected by ContentKing and supports the ISO-8601 (opens in a new tab) datetime format.

The data_captured_at parameter is supported by the following endpoints:

For example, to retrieve the statistics for a website from June 1st, 2022 at 05:00, you can send the following request:

GET /v2/data/statistics?website_id=<website_id>&captured_at=2022-06-01T05%3A00%3A00%2B00%3A00

The is_data_golden property indicates whether the response to this request is golden or not.

When the data is golden, it means that when the same request is made at a later point in time, the retrieved data will always be exactly the same.

In context of ContentKing’s data, this applies to retrieving data historically. The historical data retrieved from ContentKing will always be golden as the data cannot change anymore, as opposed to retrieving current data which is subject to change.

Common API errors

Authorization missing

401 Unauthorized
{
    "code": "auth_missing_token",
    "message": "Authentication token must be passed in Authorization HTTP header.",
    "errors": []
}

This response means that the request was received, but that it's lacking an authorization token and can therefore not be processed. Make sure to correctly set the Authorization header.

Authorization failed

401 Unauthorized
{
    "code": "auth_failed",
    "message": "Authentication token is expired or invalid.",
    "errors": []
}

If you get this response it means that the request could not be processed because the supplied API token is invalid or expired.

Reporting API Terms of Use not accepted

403 Forbidden
{
    "code": "terms_of_use_not_accepted",
    "message": "Reporting API Terms of Use have not been accepted yet. Please accept Terms of Use in Account Settings.",
    "errors": []
}

If you get this response it means that you have not accepted Reporting API Terms of Use yet. You need to accept them in Account Settings before you start using Reporting API.

Website not found

404 Not found
{
    "error": "Requested website ID was not found"
}

In case you get this response the website ID you specified can't be found in your account.

Authorization malformed

422 Unprocessable Entity
{
    "code": "auth_malformed",
    "message": "Authorization HTTP header must conform to format described in docs.",
    "errors": []
}

This response means that the request was received, but that the authorization wasn't formatted correctly. Make sure to correctly set the Authorization header.

Rate limits

Rate limits define the maximum number of requests which can be made in a given time range.

ContentKing’s Reporting API has the following rate limits:

  • 6 requests/second/requester IP address
  • When the limit is hit the API returns a 429 status code for 1 minute

The Reporting API uses rate limits to ensure API request traffic can be handled efficiently.

Need help?

If you have any questions that are not covered by our documentation, don’t hesitate to contact us!