URL Metrics

In this guide you’ll learn more about making API calls to the URL Metrics endpoint for the Links API V2.

Use this endpoint to get metrics about one or more urls.

This documentation specifies information for Moz Links API V2. V1 documentation is available here.

Please note: This is a weighted endpoint which means that data returned from this endpoint may count as more than 1 row consumed based on the data requested. Please see here for more information on weighted endpoints and multiplier logic specific to the URL Metrics endpoint.

On This Page

• Getting Started
• Endpoint Location
• Request Syntax
• Example JSON Request
• Request Parameters
• Response Syntax
• Example JSON Response
• Response Elements
• Errors
• Example HTTP Request
• Example cURL Request
• Example Python Request

Before making calls to the URL Metrics endpoint, be sure you are set up with an Access ID and Secret Key within your Moz Account.

Just a reminder - the Links API V2 supports Basic Auth in which you are able to use your Access ID as a username and and your Secret Key as a password.

All requests and responses are structured in JSON.

• Learn more about how to get a key
• Learn more about Moz Links API authentication
• Learn more about weighted endpoints

When requesting URL metrics data from Links V2, be sure to use the following endpoint.

• Use Postman? Access the Links API V2 Postman Collection

"targets" - A list of up to 50 URLs to get metrics for.

• Type: Array of string objects
• Required: yes

"daily_history_deltas" - A list of metrics to return daily history for as a sequence of dated gains and losses. Results for each metric will appear under a key matching its name in the 'daily_history_deltas' response element. Delta values for count metrics (pages_to_page, etc) will begin with the most recent gain or loss for that metric, and end no earlier than 60 days prior. Delta values for authority metrics (page_authority, domain_authority) will begin on the day the index was last updated and end no earlier than 60 days prior.

• Type: Array of string objects
• Valid Values: all non-deleted count metrics (pages_to_page, etc), page_authority, domain_authority
• Required: no

"daily_history_values" - A list of metrics to return daily history for as a sequence of date + value pairs. Results for each metric will appear under a key matching its name in the 'daily_history_values' response element. History values will begin on the day the index was last updated and end 60 days prior.

• Type: Array of string objects
• Valid Values: all non-deleted count metrics (pages_to_page, etc), page_authority, domain_authority, nofollow_pages_to_root_domain_by_spam_score, nofollow_root_domains_to_root_domain_by_root_domains, nofollow_root_domains_to_root_domain_by_spam_score, pages_to_root_domain_by_spam_score, root_domains_to_root_domain_by_root_domains, root_domains_to_root_domain_by_spam_score
• Required: no

"monthly_history_deltas" - Like the 'daily_history_deltas' request parameter, except that results appear in the 'monthly_history_deltas' response element and reflect 32 months of history.

• Type: Array of string objects
• Valid Values: all non-deleted count metrics (pages_to_page, etc), page_authority, domain_authority
• Required: no

"monthly_history_values" - Like the 'daily_history_values' request parameter, except that results appear in the 'monthly_history_values' response element and reflect 32 months of history.

• Type: Array of string objects
• Valid Values: all non-deleted count metrics (pages_to_page, etc), page_authority, domain_authority, nofollow_pages_to_root_domain_by_spam_score, nofollow_root_domains_to_root_domain_by_root_domains, nofollow_root_domains_to_root_domain_by_spam_score, pages_to_root_domain_by_spam_score, root_domains_to_root_domain_by_root_domains, root_domains_to_root_domain_by_spam_score
• Required: no

"distributions" - If true, returns the additional link distribution metrics indicated in the 'Response Syntax' section below. If false (the default), does not return these metrics. Each distribution is named with the pattern 'METRIC_by_MEASURE', where 'METRIC' has the same meaning as the stand-alone metric with the same name, and 'MEASURE' determines how that metric is split into buckets. 'MEASURE' can have the following values:

• root_domains - Metric is bucketed by the number of root domains linking to the source of each link. The ranges represented in each bucket are:
  • [0, 1-9, 10-99, 100-999, 1000-9999, 10000-99999, 100000-999999, 1000000-9999999, 10000000-99999999, 100000000+]
• domain_authority - Metric is bucketed by the domain authority of the source root domain of each link. The ranges represented in each bucket are:
  • [1-10, 11-20, 21-30, 31-40, 41-50, 51-60, 61-70, 71-80, 81-90, 91-100]
• spam_score - Metric is bucketed by the spam score of the source root domain of each link. The ranges represented in each bucket are:
  • [1-10, 11-20, 21-30, 31-40, 41-50, 51-60, 61-70, 71-80, 81-90, 91-100]
  • For some source root domains, a spam score is not available. Links from these domains are not counted in the response distribution.
• Type: boolean
• Required: no

"results" - An array of metrics with one entry for each element in the 'targets' request parameter, in the same order as the requested targets.

• Type: Array of Map objects
• Within "results" the following response elements exist:
  • "page" - The page of the target requested, after canonicalization.
    • Type: string
  • "subdomain" - The subdomain of the target requested, after canonicalization.
    • Type: string
  • "root_domain" - The root domain of the target requested, after canonicalization.
    • Type: string
  • "title" - The title of the page seen the most recent time it has been crawled, or an empty string if the page has never been crawled.
    • Type: string
  • "last_crawled" - The date the most recent time the page has been crawled in 'YYYY-MM-DD' format, or an empty string if the page has never been crawled.
    • Type: string
  • "http_code" - The status code returned by the host the most recent time the page was crawled, or 0 if the page has never been crawled. Values < 100 are reserved for internal use and indicate various types of crawl failure.
    • Type: number
  • "pages_to_page" - The number of unique pages currently linking to this page. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "nofollow_pages_to_page" - The number of unique pages currently linking to this page with only nofollow links. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "redirect_pages_to_page" - The number of unique pages currently redirecting to this page. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "external_pages_to_page" - The number of unique pages from a different root domain currently linking to this page.
    • Type: number
  • "external_nofollow_pages_to_page" - The number of unique pages from a different root domain currently linking to this page with only nofollow links.
    • Type: number
  • "external_redirect_pages_to_page" - The number of unique pages from a different root domain currently redirecting to this page.
    • Type: number
  • "deleted_pages_to_page" - The number of unique pages that used to link to this page, but no longer do.
    • Type: number
  • "root_domains_to_page" - The number of unique root domains currently linking to this page. Links from the same root domain as the target do not contribute to this count.
    • Type: number
  • "indirect_root_domains_to_page" - The number of unique root domains currently linking to this page via a redirecting page or rel-canonical link. Link chains that are entirely within the same root domain as the target do not contribute to this count.
    • Type: number
  • "deleted_root_domains_to_page" - The number of unique root domains that used to link to this page, but no longer do.
    • Type: number
  • "nofollow_root_domains_to_page" - The number of unique root domains currently linking to this page with only nofollow links. Links from the same root domain as the target do not contribute to this count.
    • Type: number
  • "pages_to_subdomain" - The number of unique pages currently linking to this subdomain. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "nofollow_pages_to_subdomain" - The number of unique pages currently linking to this subdomain with only nofollow links. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "redirect_pages_to_subdomain" - The number of unique pages currently redirecting to this subdomain. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "external_pages_to_subdomain" - The number of unique pages from a different root domain currently linking to this subdomain.
    • Type: number
  • "external_nofollow_pages_to_subdomain" - The number of unique pages from a different root domain currently linking to this subdomain with only nofollow links.
    • Type: number
  • "external_redirect_pages_to_subdomain" - The number of unique pages from a different root domain currently redirecting to this subdomain.
    • Type: number
  • "deleted_pages_to_subdomain" - The number of unique pages that used to link to this subdomain, but no longer do.
    • Type: number
  • "root_domains_to_subdomain" - The number of unique root domains currently linking to this subdomain. Links from the same root domain as the target do not contribute to this count.
    • Type: number
  • "deleted_root_domains_to_subdomain" - The number of unique root domains that used to link to this subdomain, but no longer do.
    • Type: number
  • "nofollow_root_domains_to_subdomain" - The number of unique root domains currently linking to this subdomain with only nofollow links. Links from the same root domain as the target do not contribute to this count.
    • Type: number
  • "pages_to_root_domain" - The number of unique pages currently linking to this root domain. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "nofollow_pages_to_root_domain" - The number of unique pages currently linking to this root domain with only nofollow links. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "redirect_pages_to_root_domain" - The number of unique pages currently redirecting to this root domain. Pages that link to themselves do not contribute to this count.
    • Type: number
  • "external_pages_to_root_domain" - The number of unique pages from a different root domain currently linking to this root domain.
    • Type: number
  • "external_indirect_pages_to_root_domain" - The number of unique pages from a different root domain currently linking to this page via a redirecting page or rel-canonical link.
    • Type: number
  • "external_nofollow_pages_to_root_domain" - The number of unique pages from a different root domain currently linking to this root domain with only nofollow links.
    • Type: number
  • "external_redirect_pages_to_root_domain" - The number of unique pages from a different root domain currently redirecting to this root domain.
    • Type: number
  • "deleted_pages_to_root_domain" - The number of unique pages that used to link to this root domain, but no longer do.
    • Type: number
  • "root_domains_to_root_domain" - The number of unique root domains currently linking to this root domain. Links from the same root domain as the target do not contribute to this count.
    • Type: number
  • "indirect_root_domains_to_root_domain" - The number of unique root domains currently linking to this root domain via a redirecting page or rel-canonical link. Link chains that are entirely within the same root domain as the target do not contribute to this count.
    • Type: number
  • "deleted_root_domains_to_root_domain" - The number of unique root domains that used to link to this root domain, but no longer do.
    • Type: number
  • "nofollow_root_domains_to_root_domain" -The number of unique root domains currently linking to this root domain with only nofollow links. Links from the same root domain as the target do not contribute to this count.
    • Type: number
  • "page_authority" - A score from 1 to 100 representing the likelihood that this page will rank well in search engine result pages.
    • Type: number
  • "domain_authority" - A score from 1 to 100 representing the likelihood that this root domain will rank well in search engine result pages.
    • Type: number
  • "link_propensity" - A score from 0 to 1 indicating the likelihood of the target root domain to link out to other root domains. This is currently calculated as the ratio of 'root_domains_from_root_domain' to 'pages_crawled_from_root_domain'.
    • Type: number
  • "spam_score" - The spam score for the target requested, or -1 if a spam score does not exist for that target.
    • Type: number
  • "root_domains_from_page" - The unique number of root domains linked to by the target page, or 0 if the page has never been crawled.
    • Type: number
  • "nofollow_root_domains_from_page" - The unique number of root domains linked to by the target page using only nofollow links, or 0 if the page has never been crawled.
    • Type: number
  • "pages_from_page" - The unique number of pages linked to by the target page, or 0 if the page has never been crawled.
    • Type: number
  • "nofollow_pages_from_page" - The unique number of pages linked to by the target page using only nofollow links, or 0 if the page has never been crawled.
    • Type: number
  • "root_domains_from_root_domain" - The unique number of root domains linked to by the target root domain, or 0 if no pages on the root domain have ever been crawled.
    • Type: number
  • "nofollow_root_domains_from_root_domain" - The unique number of root domains linked to by the target root domain using only nofollow links, or 0 if no pages on the root domain have ever been crawled.
    • Type: number
  • "pages_from_root_domain" - The unique number of pages linked to by the target root domain, or 0 if no pages on the root domain have ever been crawled.
    • Type: number
  • "nofollow_pages_from_root_domain" - The unique number of pages linked to by the target root domain using only nofollow links, or 0 if the page has never been crawled.
    • Type: number
  • "pages_crawled_from_root_domain" - The number of pages on the target root domain that have been successfully crawled (i.e., a response was recieved from the host, regardless of the http status code associated with that response).
    • Type: number
  • "root_domains_to_page_by_root_domains" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_root_domain_by_root_domains" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "nofollow_root_domains_to_root_domain_by_root_domains" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_page_by_domain_authority" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_subdomain_by_domain_authority" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_root_domain_by_domain_authority" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "nofollow_root_domains_to_root_domain_by_domain_authority" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "pages_to_root_domain_by_spam_score" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "nofollow_pages_to_root_domain_by_spam_score" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_page_by_spam_score" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_subdomain_by_spam_score" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "root_domains_to_root_domain_by_spam_score" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "nofollow_root_domains_to_root_domain_by_spam_score" - See the 'distributions' request parameter for a description of this response element.
    • Type: Array of numbers
  • "daily_history_deltas" - A map from metric name to a sequence of dated gains and losses for each requested metric.
    • Type: Map object
    • When "daily_history_deltas" is non-empty:
      • "gained" - A sequence of dated gains for a metric.
        • Type: Array of Map objects
          • "Date" - The date of the loss in 'YYYY-MM-DD' format.
            • Type: string
          • "Count" - The amount the metric increased.
            • Type: number
      • "lost" - A sequence of dated losses for a metric.
        • Type: Array of Map objects
          • "Date" - The date of the loss in 'YYYY-MM-DD' format.
            • Type: string
          • "Count" - The amount the metric decreased.
            • Type: number
  • "monthly_history_deltas" - A map from metric name to a sequence of dated gains and losses for each requested metric.
    • Type: Map object
    • When "monthly_history_deltas" is non-empty:
      • "gained" - A sequence of dated gains for a metric.
        • Type: Array of Map objects
        • "Date" - The date of the loss in 'YYYY-MM' format.
          • Type: string
        • "Count" - The amount the metric increased.
          • Type: number
      • "lost" - A sequence of dated losses for a metric.
        • Type: Array of Map objects
        • "Date" - The date of the loss in 'YYYY-MM' format.
          • Type: string
        • "Count" - The amount the metric decreased.
          • Type: number
  • "daily_history_values" - A map from metric name to a sequence of date and value pairs for each requested metric.
    • Type: Map object
    • When "daily_history_values" is non-empty
      • "date" - A date in 'YYYY-MM-DD' format.
        • Type: string
      • "count" - The value of the associated metric on 'date'.
        • Type: number
  • "monthly_history_values" - A map from metric name to a sequence of date and value pairs for each requested metric.
    • Type: Map object
    • When "monthly_history_values" is non-empty:
      • "date" - A date in 'YYYY-MM' format.
        • Type: string
      • "count" - The value of the associated metric on 'date'.
        • Type: number

See the Common Errors section for errors that are common to all endpoints.