> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changes

> What changed about an entity since a date, from the facts we have recorded

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

<ParamField body="attribute" type="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.
</ParamField>

<ParamField body="key" type="string">
  The entity key the data tool uses (a vehicle identification number in capitals). Give exactly one of `key` and `input`.
</ParamField>

<ParamField body="input" type="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`.
</ParamField>

<ParamField body="source" type="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.
</ParamField>

<ParamField body="since" type="string" required>
  First day of the window, `YYYY-MM-DD`.
</ParamField>

<ParamField body="until" type="string">
  Last day of the window, `YYYY-MM-DD`. Default: today.
</ParamField>

<ParamField body="limit" type="integer" default={50}>
  Most changes to return, oldest first (1-200).
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200)

<ResponseField name="data.attribute" type="string">
  The data tool asked about
</ResponseField>

<ResponseField name="data.key" type="string">
  The entity key. For a search, the hash of its normalized input.
</ResponseField>

<ResponseField name="data.recorded_since" type="string | null">
  The day of our first record (`YYYY-MM-DD`), or `null` when nothing is recorded
</ResponseField>

<ResponseField name="data.partial" type="boolean">
  `true` when `since` is earlier than `recorded_since`
</ResponseField>

<ResponseField name="data.changes" type="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`.
</ResponseField>

<ResponseField name="data.truncated" type="boolean">
  `true` when the window holds more changes than `limit`
</ResponseField>

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.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/changes \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "attribute": "vehicle_identification",
      "key": "1HGCM82633A004352",
      "since": "2026-01-01"
    }'
  ```

  ```typescript SDK theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  const result = await agent.tool("changes", {
    attribute: "vehicle_identification",
    key: "1HGCM82633A004352",
    since: "2026-01-01",
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "request_id": "6f1c2a94-0d1e-4b53-9d0e-2f6f0c1f7a11",
      "status": "completed",
      "tool": "changes",
      "attribute": "vehicle_identification",
      "key": "1HGCM82633A004352",
      "recorded_since": "2026-03-02",
      "partial": false,
      "changes": [
        {
          "changed_on": "2026-06-10",
          "field": "make",
          "before": "HONDA",
          "after": "HONDA MOTOR",
          "source": "US National Highway Traffic Safety Administration",
          "as_of": null
        }
      ],
      "truncated": false
    }
  }
  ```
</ResponseExample>

<Info>See [Pricing](/pricing) for the price of a call.</Info>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.