Skip to main content
POST

​
Overview

Returns the dated changes we have recorded about one entity: for each, the earlier value, the later value, when we first saw the later one, and the source. One tool serves every data tool that keeps history. attribute names the data tool, for example vehicle_identification. Results return in the response, with no polling. A window with no changes is a completed, charged result.

​
What “recorded since” means

We only know what we have seen. Every completed call to a data tool is kept, and a new record is made only when the value differs from the last one we saw for that entity and source. recorded_since is the day of our first record of the entity. It is not the day the entity first existed, and it says nothing about the period before it. When since is earlier than recorded_since, the response has partial: true: changes before recorded_since may have happened and we did not see them. When nothing is recorded for the entity, recorded_since is null and partial is true. A change is dated by the day we first saw the later value (UTC), not the day the source changed it. as_of is the date the source gave for the later value, or null.

​
Authentication

Requires x402 payment in the payment-signature header.

​
Request Body

​
string
required
The name of a data tool that keeps history, for example vehicle_identification. A name that keeps no history is refused before payment, and the response lists the names that do.
​
string
The entity key the data tool uses (a vehicle identification number in capitals). Give exactly one of key and input.
​
object
The input a search was called with, to read the history of that search. It is matched by a hash and is not stored. Give exactly one of key and input.
​
string
The source to read, when the entity has history from more than one. Without it, such a request is refused and the response lists the sources.
​
string
required
First day of the window, YYYY-MM-DD.
​
string
Last day of the window, YYYY-MM-DD. Default: today.
​
integer
default:50
Most changes to return, oldest first (1-200).

​
Response (200)

​
string
The data tool asked about
​
string
The entity key. For a search, the hash of its normalized input.
​
string | null
The day of our first record (YYYY-MM-DD), or null when nothing is recorded
​
boolean
true when since is earlier than recorded_since
​
array
Each with changed_on, field, before, after, source and as_of. field is the path of the changed field (engine.cylinders, recalls[2].status). When the entity stops being listed by the source, or appears again, field is $entity and before and after are listed or not_listed.
​
boolean
true when the window holds more changes than limit
You can read the history of data you paid for yourself. Facts from public sources are visible to every caller. Results from other providers, and facts about private individuals, are visible only to the agent whose call recorded them.
See Pricing for the price of a call.

​
Errors

  • 400 invalid_input: the attribute is not a data tool or keeps no history (the response lists those that do), or a stored search input is not a valid input of that data tool.
  • 400 invalid_request: a date is not a real YYYY-MM-DD date, until is before since, not exactly one of key and input was given, or a stored search input is longer than 10,000 characters.
These are refused before any payment. The entity having several sources while source is missing is also 400 invalid_input (the response lists the sources), but it can only be found after payment is taken. The call is recorded as failed and the response carries its request_id and receipt_id; a failed call of this kind is refunded automatically. Name a source to avoid it.