Conductor Monitoring Reporting API

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

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 Conductor Monitoring account's Reporting API token. You'll find it in the Account section, under the Integration tokens 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

Conductor Monitoring 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": "Conductor Monitoring - DE",
      "page_capacity": 1000
    },
  ]
}

Data types overview for this endpoint

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

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

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, page, and page_cursor 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
• page_cursor is a string retrieved from the next_page_cursor field in the API response for the previous page

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, page, and page_cursor

{
  "data": {
  "next_page_cursor": "WyIvencvY3NoZWxwL2FydGljbGUv2YPZit"
  "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,
        "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

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,
  "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,
    "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

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 Conductor Monitoring.

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 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

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

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

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
}

Data types overview for this endpoint

List of issues

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 Conductor Monitoring and supports the ISO-8601 datetime format.

The data_captured_at parameter is supported by the following endpoints:

• Retrieving statistics for a website or segment
• Retrieving a list of issues for a website or segment

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

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

The Reporting API uses rate limits to ensure API request traffic can be handled efficiently. Rate limits define the maximum number of requests which can be made in a given time range.

Conductor Monitoring’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

Note that there is no maximum number of calls you can make to this API.