{"_id":"581a19f11a63870f008b61ee","user":"560b40145148ba0d009bd0b5","category":{"_id":"5615790d0f5ed00d00483dd5","__v":19,"pages":["5615790e0f5ed00d00483dd7","561d48e46386060d00e06003","561d48fe31d9630d001eb5bd","561d49b657165b0d00aa5d8b","561d4a879463520d00cd11e2","561d67f48ca8b90d00210234","561d6a0bf0cff80d00ca22c3","561d6c5b071cd60d000d3221","562f9c2543c5570d001fe6bd","56311c99eae7ef0d00270e3d","56311d6702aff217007dba23","56311f96f1c0580d00fac719","563120b7242cda1900198b79","5631229bf1c0580d00fac721","563131559ead230d00a188f6","563134a324014b0d00bd9a4f","5631392082d96a0d00b0fb1d","56313c584b36120d00fdebfb","5642658ef424a10d00118360"],"project":"5615790c0f5ed00d00483dd1","version":"5615790d0f5ed00d00483dd4","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-07T19:57:01.871Z","from_sync":false,"order":0,"slug":"opendns-investigate-rest-api","title":"Umbrella Investigate REST API"},"project":"5615790c0f5ed00d00483dd1","version":{"_id":"5615790d0f5ed00d00483dd4","__v":6,"project":"5615790c0f5ed00d00483dd1","createdAt":"2015-10-07T19:57:01.307Z","releaseDate":"2015-10-07T19:57:01.307Z","categories":["5615790d0f5ed00d00483dd5","56157b2af432910d0000f9fe","56157cfb0f5ed00d00483ddb","562684d95db46b1700fd4f48","573b7ea9ef164e2900a2b8ff","582e285d8373c20f00810608"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-02T16:53:05.638Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":12,"body":"The DNS database can be used to query the history that Umbrella has seen for a given domain.\n\nThe most common use case is to obtain the RRs (Resource Record) history for a given domain, passing in the record query type as a parameter, to help build intelligence around an domain. This API method returns the history of a DNS resource record for a given name, such as the list of IP addresses that a name maps to, and used to map to. The information provided is from within the last 90 days.\n\nTo gather a list of the nameservers for a domain, specify the DNS query type as NS. The list of nameservers for a domain gathered by this list may differ from the the list of nameservers gathered from the WHOIS data because the information here is dynamically gathered from DNS query data.\n\nSample query:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" \\\"https://investigate.api.umbrella.com/dnsdb/name/a/example.com.json\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n### Parameter for input ###\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"type\",\n    \"0-1\": \"string\",\n    \"1-0\": \"name\",\n    \"1-1\": \"string\",\n    \"1-2\": \"Domain name.\",\n    \"0-2\": \"DNS record query type (A, NS, MX, TXT and CNAME are supported).\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n### Returned value for output if Success 200 ###\n\n__Response Class:__\nResource Records\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"first_seen\",\n    \"0-1\": \"string\",\n    \"1-0\": \"last_seen\",\n    \"1-1\": \"string\",\n    \"2-0\": \"name\",\n    \"2-1\": \"string\",\n    \"3-0\": \"ttl\",\n    \"3-1\": \"integer\",\n    \"4-0\": \"class\",\n    \"4-1\": \"string\",\n    \"5-0\": \"type\",\n    \"5-1\": \"string\",\n    \"6-0\": \"rr\",\n    \"6-1\": \"string\",\n    \"0-2\": \"Date when the domain was first seen to our DNS database.\",\n    \"1-2\": \"Date when domain was last seen in our DNS database.\",\n    \"2-2\": \"Name of the domain.\",\n    \"3-2\": \"Name of the domain.\",\n    \"4-2\": \"DNS class type.\",\n    \"5-2\": \"Query type.\",\n    \"6-2\": \"Resource record IP for the domain.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\n__Response Class:__\nFeatures\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"age\",\n    \"0-1\": \"integer\",\n    \"0-2\": \"The day in days between now and the last request for this domain. This value is only useful if present. A low score helps isolate attack domains that are short-lived.\",\n    \"1-2\": \"Minimum amount of time set that DNS records should be cached\",\n    \"2-2\": \"Maximum amount of time set that DNS records should be cached.\",\n    \"3-2\": \"Average amount of time set that DNS records should be cached.\",\n    \"4-2\": \"Median amount of time set that DNS records should be cached.\",\n    \"5-2\": \"Standard deviation of the amount of time set that DNS records should be cached.\",\n    \"1-0\": \"ttls_min\",\n    \"2-0\": \"ttls_max\",\n    \"3-0\": \"ttls_mean\",\n    \"4-0\": \"ttls_median\",\n    \"5-0\": \"ttls_stddev\",\n    \"1-1\": \"integer\",\n    \"2-1\": \"integer\",\n    \"3-1\": \"float\",\n    \"4-1\": \"float\",\n    \"5-1\": \"float\",\n    \"6-0\": \"country_codes\",\n    \"6-1\": \"array\",\n    \"6-2\": \"List of country codes (ex: US, FR, TW) for the IPs the name maps to.\",\n    \"7-2\": \"Number of countries the IPs are hosted in.\",\n    \"7-1\": \"integer\",\n    \"7-0\": \"country_count\",\n    \"8-0\": \"asns\",\n    \"8-1\": \"array\",\n    \"8-2\": \"List of ASN numbers the IPs are in.\",\n    \"9-2\": \"Number of ASNs the IPs map to.\",\n    \"9-1\": \"integer\",\n    \"9-0\": \"asns_count\",\n    \"10-0\": \"prefixes\",\n    \"10-1\": \"array\",\n    \"10-2\": \"List of network prefixes the IPs map to.\",\n    \"11-0\": \"prefixes_count\",\n    \"11-1\": \"float\",\n    \"11-2\": \"Number of network prefixes the IPs map to.\",\n    \"12-0\": \"rips\",\n    \"12-1\": \"integer\",\n    \"12-2\": \"Number of IPs seen for the domain name.\",\n    \"13-0\": \"div_rips\",\n    \"13-1\": \"float\",\n    \"13-2\": \"The number of prefixes over the number of IPs.\",\n    \"14-0\": \"locations\",\n    \"14-1\": \"array\",\n    \"14-2\": \"List of geo coordinates (WGS84 datum, decimal format) the IPs are mapping to.\",\n    \"15-0\": \"locations_count\",\n    \"16-0\": \"geo_distance_sum\",\n    \"17-0\": \"geo_distance_mean\",\n    \"18-0\": \"non_routable\",\n    \"19-0\": \"mail_exchanger\",\n    \"20-0\": \"cname\",\n    \"21-0\": \"ff_candidate\",\n    \"22-0\": \"rips_stability\",\n    \"23-0\": \"base_domain\",\n    \"24-0\": \"is_subdomain\",\n    \"15-1\": \"integer\",\n    \"15-2\": \"Number of distinct geo coordinates the IPs are mapping to.\",\n    \"16-2\": \"Minimum sum of distance between locations, in kilometers.\",\n    \"17-2\": \"Mean distance between the geo median and each location, in kilometers.\",\n    \"18-2\": \"If one of the IPs is in a reserved, non-routable IP range.\",\n    \"19-2\": \"If an MX query for this domain name has been seen.\",\n    \"20-2\": \"Returns true if a CNAME record has been seen for this domain name.\",\n    \"21-2\": \"If the domain name looks like a candidate for [fast flux](http://en.wikipedia.org/wiki/Fast_flux). This does not necessarily mean the domain is in fast flux, but rather that the IP address the domain resolves to changes rapidly (or has changed rapidly).\",\n    \"22-2\": \"1.0 divided by the number of times the set of IP addresses changed.\",\n    \"23-2\": \"The base domain of the requested domain.\",\n    \"24-2\": \"Returns true if the requested domain is a subdomain of another.\",\n    \"24-1\": \"boolean\",\n    \"23-1\": \"string\",\n    \"22-1\": \"float\",\n    \"21-1\": \"boolean\",\n    \"20-1\": \"boolean\",\n    \"19-1\": \"boolean\",\n    \"18-1\": \"boolean\",\n    \"17-1\": \"float\",\n    \"16-1\": \"float\"\n  },\n  \"cols\": 3,\n  \"rows\": 25\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/dnsdb/name/type/name.json\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n     --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\nhttps://investigate.api.umbrella.com/dnsdb/name/{type}/{name}.json\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n{\\n  \\\"rrs_tf\\\": [\\n    {\\n      \\\"first_seen\\\": \\\"2013-07-31\\\",\\n      \\\"last_seen\\\": \\\"2013-10-17\\\",\\n      \\\"rrs\\\": [\\n        {\\n          \\\"name\\\": \\\"example.com.\\\",\\n          \\\"ttl\\\": 86400,\\n          \\\"class\\\": \\\"IN\\\",\\n          \\\"type\\\": \\\"A\\\",\\n          \\\"rr\\\": \\\"93.184.216.119\\\"\\n        }\\n      ]\\n    },\\n    {\\n      \\\"first_seen\\\": \\\"2013-07-30\\\",\\n      \\\"last_seen\\\": \\\"2013-07-30\\\",\\n      \\\"rrs\\\": [\\n        {\\n          \\\"name\\\": \\\"example.com.\\\",\\n          \\\"ttl\\\": 172800,\\n          \\\"class\\\": \\\"IN\\\",\\n          \\\"type\\\": \\\"A\\\",\\n          \\\"rr\\\": \\\"192.0.43.10\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"example.com.\\\",\\n          \\\"ttl\\\": 86400,\\n          \\\"class\\\": \\\"IN\\\",\\n          \\\"type\\\": \\\"A\\\",\\n          \\\"rr\\\": \\\"93.184.216.119\\\"\\n        }\\n      ]\\n    },\\n    {\\n      \\\"first_seen\\\": \\\"2013-07-18\\\",\\n      \\\"last_seen\\\": \\\"2013-07-29\\\",\\n      \\\"rrs\\\": [\\n        {\\n          \\\"name\\\": \\\"example.com.\\\",\\n          \\\"ttl\\\": 172800,\\n          \\\"class\\\": \\\"IN\\\",\\n          \\\"type\\\": \\\"A\\\",\\n          \\\"rr\\\": \\\"192.0.43.10\\\"\\n        }\\n      ]\\n    }\\n  ],\\n  \\\"features\\\": {\\n    \\\"age\\\": 91,\\n    \\\"ttls_min\\\": 86400,\\n    \\\"ttls_max\\\": 172800,\\n    \\\"ttls_mean\\\": 129600,\\n    \\\"ttls_median\\\": 129600,\\n    \\\"ttls_stddev\\\": 43200,\\n    \\\"country_codes\\\": [\\n      \\\"US\\\"\\n    ],\\n    \\\"country_count\\\": 1,\\n    \\\"asns\\\": [\\n      15133,\\n      40528\\n    ],\\n    \\\"asns_count\\\": 2,\\n    \\\"prefixes\\\": [\\n      \\\"93.184.208.0\\\",\\n      \\\"192.0.43.0\\\"\\n    ],\\n    \\\"prefixes_count\\\": 2,\\n    \\\"rips\\\": 2,\\n    \\\"div_rips\\\": 1,\\n    \\\"locations\\\": [\\n      {\\n        \\\"lat\\\": 38,\\n        \\\"lon\\\": -97\\n      },\\n      {\\n        \\\"lat\\\": 33.78659999999999,\\n        \\\"lon\\\": -118.2987\\n      }\\n    ],\\n    \\\"locations_count\\\": 2,\\n    \\\"geo_distance_sum\\\": 1970.1616237100388,\\n    \\\"geo_distance_mean\\\": 985.0808118550194,\\n    \\\"non_routable\\\": false,\\n    \\\"mail_exchanger\\\": false,\\n    \\\"cname\\\": false,\\n    \\\"ff_candidate\\\": false,\\n    \\\"rips_stability\\\": 0.5,\\n    \\\"base_domain\\\": \\\"example.com\\\",\\n    \\\"is_subdomain\\\": false\\n  }\\n}\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\n---\n[Domain Tagging Dates for a Domain](https://docs.umbrella.com/developer/investigate-api/domain-tagging-dates-for-a-domain-1/) < **DNS RR History for a Type and Domain Name** > [DNS RR History for an IP Address](https://docs.umbrella.com/developer/investigate-api/dns-rr-history-for-an-ip-address-1/)","excerpt":"","slug":"dns-rr-history-for-a-type-and-domain-name-1","type":"basic","title":"DNS RR History for a Type and Domain Name"}

DNS RR History for a Type and Domain Name


The DNS database can be used to query the history that Umbrella has seen for a given domain. The most common use case is to obtain the RRs (Resource Record) history for a given domain, passing in the record query type as a parameter, to help build intelligence around an domain. This API method returns the history of a DNS resource record for a given name, such as the list of IP addresses that a name maps to, and used to map to. The information provided is from within the last 90 days. To gather a list of the nameservers for a domain, specify the DNS query type as NS. The list of nameservers for a domain gathered by this list may differ from the the list of nameservers gathered from the WHOIS data because the information here is dynamically gathered from DNS query data. Sample query: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" \"https://investigate.api.umbrella.com/dnsdb/name/a/example.com.json\"", "language": "text" } ] } [/block] ### Parameter for input ### [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "type", "0-1": "string", "1-0": "name", "1-1": "string", "1-2": "Domain name.", "0-2": "DNS record query type (A, NS, MX, TXT and CNAME are supported)." }, "cols": 3, "rows": 2 } [/block] ### Returned value for output if Success 200 ### __Response Class:__ Resource Records [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "first_seen", "0-1": "string", "1-0": "last_seen", "1-1": "string", "2-0": "name", "2-1": "string", "3-0": "ttl", "3-1": "integer", "4-0": "class", "4-1": "string", "5-0": "type", "5-1": "string", "6-0": "rr", "6-1": "string", "0-2": "Date when the domain was first seen to our DNS database.", "1-2": "Date when domain was last seen in our DNS database.", "2-2": "Name of the domain.", "3-2": "Name of the domain.", "4-2": "DNS class type.", "5-2": "Query type.", "6-2": "Resource record IP for the domain." }, "cols": 3, "rows": 7 } [/block] __Response Class:__ Features [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "age", "0-1": "integer", "0-2": "The day in days between now and the last request for this domain. This value is only useful if present. A low score helps isolate attack domains that are short-lived.", "1-2": "Minimum amount of time set that DNS records should be cached", "2-2": "Maximum amount of time set that DNS records should be cached.", "3-2": "Average amount of time set that DNS records should be cached.", "4-2": "Median amount of time set that DNS records should be cached.", "5-2": "Standard deviation of the amount of time set that DNS records should be cached.", "1-0": "ttls_min", "2-0": "ttls_max", "3-0": "ttls_mean", "4-0": "ttls_median", "5-0": "ttls_stddev", "1-1": "integer", "2-1": "integer", "3-1": "float", "4-1": "float", "5-1": "float", "6-0": "country_codes", "6-1": "array", "6-2": "List of country codes (ex: US, FR, TW) for the IPs the name maps to.", "7-2": "Number of countries the IPs are hosted in.", "7-1": "integer", "7-0": "country_count", "8-0": "asns", "8-1": "array", "8-2": "List of ASN numbers the IPs are in.", "9-2": "Number of ASNs the IPs map to.", "9-1": "integer", "9-0": "asns_count", "10-0": "prefixes", "10-1": "array", "10-2": "List of network prefixes the IPs map to.", "11-0": "prefixes_count", "11-1": "float", "11-2": "Number of network prefixes the IPs map to.", "12-0": "rips", "12-1": "integer", "12-2": "Number of IPs seen for the domain name.", "13-0": "div_rips", "13-1": "float", "13-2": "The number of prefixes over the number of IPs.", "14-0": "locations", "14-1": "array", "14-2": "List of geo coordinates (WGS84 datum, decimal format) the IPs are mapping to.", "15-0": "locations_count", "16-0": "geo_distance_sum", "17-0": "geo_distance_mean", "18-0": "non_routable", "19-0": "mail_exchanger", "20-0": "cname", "21-0": "ff_candidate", "22-0": "rips_stability", "23-0": "base_domain", "24-0": "is_subdomain", "15-1": "integer", "15-2": "Number of distinct geo coordinates the IPs are mapping to.", "16-2": "Minimum sum of distance between locations, in kilometers.", "17-2": "Mean distance between the geo median and each location, in kilometers.", "18-2": "If one of the IPs is in a reserved, non-routable IP range.", "19-2": "If an MX query for this domain name has been seen.", "20-2": "Returns true if a CNAME record has been seen for this domain name.", "21-2": "If the domain name looks like a candidate for [fast flux](http://en.wikipedia.org/wiki/Fast_flux). This does not necessarily mean the domain is in fast flux, but rather that the IP address the domain resolves to changes rapidly (or has changed rapidly).", "22-2": "1.0 divided by the number of times the set of IP addresses changed.", "23-2": "The base domain of the requested domain.", "24-2": "Returns true if the requested domain is a subdomain of another.", "24-1": "boolean", "23-1": "string", "22-1": "float", "21-1": "boolean", "20-1": "boolean", "19-1": "boolean", "18-1": "boolean", "17-1": "float", "16-1": "float" }, "cols": 3, "rows": 25 } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/dnsdb/name/type/name.json\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\nhttps://investigate.api.umbrella.com/dnsdb/name/{type}/{name}.json\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n{\n \"rrs_tf\": [\n {\n \"first_seen\": \"2013-07-31\",\n \"last_seen\": \"2013-10-17\",\n \"rrs\": [\n {\n \"name\": \"example.com.\",\n \"ttl\": 86400,\n \"class\": \"IN\",\n \"type\": \"A\",\n \"rr\": \"93.184.216.119\"\n }\n ]\n },\n {\n \"first_seen\": \"2013-07-30\",\n \"last_seen\": \"2013-07-30\",\n \"rrs\": [\n {\n \"name\": \"example.com.\",\n \"ttl\": 172800,\n \"class\": \"IN\",\n \"type\": \"A\",\n \"rr\": \"192.0.43.10\"\n },\n {\n \"name\": \"example.com.\",\n \"ttl\": 86400,\n \"class\": \"IN\",\n \"type\": \"A\",\n \"rr\": \"93.184.216.119\"\n }\n ]\n },\n {\n \"first_seen\": \"2013-07-18\",\n \"last_seen\": \"2013-07-29\",\n \"rrs\": [\n {\n \"name\": \"example.com.\",\n \"ttl\": 172800,\n \"class\": \"IN\",\n \"type\": \"A\",\n \"rr\": \"192.0.43.10\"\n }\n ]\n }\n ],\n \"features\": {\n \"age\": 91,\n \"ttls_min\": 86400,\n \"ttls_max\": 172800,\n \"ttls_mean\": 129600,\n \"ttls_median\": 129600,\n \"ttls_stddev\": 43200,\n \"country_codes\": [\n \"US\"\n ],\n \"country_count\": 1,\n \"asns\": [\n 15133,\n 40528\n ],\n \"asns_count\": 2,\n \"prefixes\": [\n \"93.184.208.0\",\n \"192.0.43.0\"\n ],\n \"prefixes_count\": 2,\n \"rips\": 2,\n \"div_rips\": 1,\n \"locations\": [\n {\n \"lat\": 38,\n \"lon\": -97\n },\n {\n \"lat\": 33.78659999999999,\n \"lon\": -118.2987\n }\n ],\n \"locations_count\": 2,\n \"geo_distance_sum\": 1970.1616237100388,\n \"geo_distance_mean\": 985.0808118550194,\n \"non_routable\": false,\n \"mail_exchanger\": false,\n \"cname\": false,\n \"ff_candidate\": false,\n \"rips_stability\": 0.5,\n \"base_domain\": \"example.com\",\n \"is_subdomain\": false\n }\n}\n </pre>\n </div>\n</div>" } [/block] --- [Domain Tagging Dates for a Domain](https://docs.umbrella.com/developer/investigate-api/domain-tagging-dates-for-a-domain-1/) < **DNS RR History for a Type and Domain Name** > [DNS RR History for an IP Address](https://docs.umbrella.com/developer/investigate-api/dns-rr-history-for-an-ip-address-1/)