API Keys & Usage
Each paid account is associated with an API Key, which has a set number of requestable "rows" per month.
The row usages reset on the day that the account subscription renews.
Each API route requires that you send your API key in either the query parameters under api_key, or in the headers under X-API-KEY.
What counts as a row?
A "row" is a unique entity or relationship returned.
For example, the response below has 3 unique nodes and unique 2 edges, which means this would be 5 rows:
{
"rows_returned": 5,
"connections": [
{
"source_entity": {
"ent_name": "John William Kirby Kelley",
"ent_type": "PERSON",
"ent_uuid": "2fde488e-28c7-4662-8e81-970508ecdd64",
"ent_aliases": [
"Kelley"
]
},
"connection_data": {
"type": "WorksFor",
"article_title": "Alleged Member of Neo-Nazi Swatting Group Charged – Krebs on Security",
"article_url": "https://krebsonsecurity.com/2020/01/alleged-member-of-neo-nazi-swatting-group-charged/",
"article_site": "https://krebsonsecurity.com/",
"article_date": "2020-01-10",
"context": "” Kelley allegedly explained to fellow Deadnet members he hoped the swatting would"
},
"target_entity": {
"ent_name": "Deadnet",
"ent_type": "ORG",
"ent_uuid": "5ed68a8c-48b4-4cf0-b50d-3c79dd56e7dc",
"ent_aliases": []
}
},
{
"source_entity": {
"ent_name": "John William Kirby Kelley",
"ent_type": "PERSON",
"ent_uuid": "2fde488e-28c7-4662-8e81-970508ecdd64",
"ent_aliases": [
"Kelley"
]
},
"connection_data": {
"type": "WorksFor",
"article_title": "Alleged Member of Neo-Nazi Swatting Group Charged – Krebs on Security",
"article_url": "https://krebsonsecurity.com/2020/01/alleged-member-of-neo-nazi-swatting-group-charged/",
"article_site": "https://krebsonsecurity.com/",
"article_date": "2020-01-10",
"context": "Kelley was a student studying cybersecurity at Old Dominion University"
},
"target_entity": {
"ent_name": "Old Dominion University",
"ent_type": "ORG",
"ent_uuid": "170dd88e-9de6-419a-b5b9-bc40c9a518df",
"ent_aliases": [
"ODU"
]
}
}
]
}Each API response returns a rows_returned key which indicates exactly how many rows were billed for the request.
Request limits / Insufficient Rows
Permission to make a request is based on the maximum possible rows returned from a request.
For example, if an /api/entities request has a specified limit=10000, the API Key must have 10,000 rows available, regardless of how many rows the request will actually return.
That said, you will only ever be billed for the rows actually returned in the response.
For this reason, request limits are set low by default, and it is recommended to set the limit according to how much data you wish to receive.
This is more complex with the connection and pathfinding routes.
With connection_limit=10, permission to make this request requires that the user have 10 connections worth of rows, or 30 rows.
With path_limit=10, permission to make this request requires that the user have 10 paths worth of rows, or ~190 rows.