```{eval-rst}
.. tutorials-retrieve-data-contract-history:
```

# Retrieve data contract history

In this tutorial we will retrieve the history of a data contract created in the [Register a Data
Contract tutorial](../../tutorials/contracts-and-documents/register-a-data-contract.md). Only
contracts that have enabled the `keepsHistory` option during contract creation will store revision
information.

:::{note}
This retrieves revisions of the contract definition. It does not return the revision history of
individual documents (see [`getDocumentHistory`](../../reference/dapi-endpoints-platform-endpoints.md#getdocumenthistory))
or records of document transfers and sales (see [document ownership and pricing
history](../../reference/glossary.md#history-document-ownership-and-pricing)).
:::

## Prerequisites

* [General prerequisites](../../tutorials/introduction.md#prerequisites) (Node.js / Dash SDK installed)
* A configured client: [Setup SDK Client](../setup-sdk-client.md)
* A Dash Platform contract ID for a contract configured to keep history: [Tutorial: Register a Data Contract](../../tutorials/contracts-and-documents/register-a-data-contract.md)

## Code

```{code-block} javascript
:caption: contract-retrieve-history.mjs

import { setupDashClient } from '../setupDashClient.mjs';

const { sdk } = await setupDashClient();

// Default tutorial contract with history (testnet). Replace or override via DATA_CONTRACT_ID.
const DATA_CONTRACT_ID =
  process.env.DATA_CONTRACT_ID ||
  '5J4VPym1Bnc2Ap9bbo9wNw6fZLGsCzDM7ZScdzcggN1r';

try {
  const history = await sdk.contracts.getHistory({
    dataContractId: DATA_CONTRACT_ID,
  });

  for (const [timestamp, contract] of history) {
    console.log(`Version at ${timestamp}:`, contract.toJSON());
  }
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}
```

```{raw} html
<div class="interactive-tutorial interactive-tutorial--integrated" data-operation="contract-history" data-network="testnet" data-renderer="history">
  <div class="interactive-tutorial__toolbar">
    <strong>Run this example on testnet</strong>
    <span class="interactive-tutorial__connection" data-role="connection"></span>
  </div>
  <label class="interactive-tutorial__label" for="contract-history-id">Data contract ID</label>
  <div class="interactive-tutorial__controls">
    <input id="contract-history-id" class="interactive-tutorial__input"
      data-param="dataContractId" data-label="a data contract ID"
      data-default-value="5J4VPym1Bnc2Ap9bbo9wNw6fZLGsCzDM7ZScdzcggN1r"
      type="text" spellcheck="false" autocomplete="off" required>
    <button class="interactive-tutorial__button" data-role="run" type="button">Run query</button>
    <button class="interactive-tutorial__button interactive-tutorial__button--text" data-role="reset" type="button">Reset</button>
  </div>
  <details class="interactive-tutorial__source">
    <summary>View browser code</summary>
    <pre><code data-role="source"></code></pre>
  </details>
  <div class="interactive-tutorial__result" data-role="result" aria-live="polite">
    <div class="interactive-tutorial__empty">Run the query to inspect contract revisions.</div>
  </div>
</div>
```

## Example data contract history

The following example response shows a retrieved contract history:

```text
Version at 1772722751435: {
  '$format_version': '1',
  id: '5J4VPym1Bnc2Ap9bbo9wNw6fZLGsCzDM7ZScdzcggN1r',
  config: {
    '$format_version': '1',
    canBeDeleted: false,
    readonly: false,
    keepsHistory: true,
    documentsKeepHistoryContractDefault: false,
    documentsMutableContractDefault: true,
    documentsCanBeDeletedContractDefault: true,
    requiresIdentityEncryptionBoundedKey: null,
    requiresIdentityDecryptionBoundedKey: null,
    sizedIntegerTypes: true
  },
  version: 1,
  ownerId: 'FKZZFDTfGdSWUmL2g7H9e46pMJMPQp9DHQcvjrsS6884',
  schemaDefs: null,
  documentSchemas: {
    note: {
      type: 'object',
      properties: [Object],
      additionalProperties: false
    }
  },
  createdAt: 1772722751435,
  updatedAt: null,
  createdAtBlockHeight: 273561,
  updatedAtBlockHeight: null,
  createdAtEpoch: 14269,
  updatedAtEpoch: null,
  groups: {},
  tokens: {},
  keywords: [],
  description: null
}
```

:::{note}
Please refer to the [data contract reference page](../../reference/data-contracts.md) for more comprehensive details related to contracts and documents.
:::

## What's Happening

After we initialize the client, we request a contract's history. The contract ID defaults to a
testnet tutorial contract but can be overridden via the `DATA_CONTRACT_ID` environment variable. The
`sdk.contracts.getHistory` method takes an object with a `dataContractId` property. It returns a
`Map` where each key is a timestamp (`BigInt`) and each value is the contract at that revision.
After the contract history is retrieved, we iterate over the entries and display each revision on the
console.