> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need. # Dataset Status Once you [deploy](/managing-amp/datasets#deploy-a-dataset) a dataset revision, its status tells you whether the deployment is running, how far each table has gotten, how far behind the chain it is, how many files garbage collection has left to delete, and why it failed if it did. ## Prerequisites * Amp running, with its Admin API reachable, and `ampctl` installed, as in [Managing Datasets](/managing-amp/datasets#prerequisites). * A deployed dataset revision, like `acme/eth_mainnet@1.0.0` from the [Quickstart](/get-started/quickstart). ## Check a deployment's status :::code-group ```bash [ampctl] ampctl dataset status acme/eth_mainnet@1.0.0 ``` ```bash [Admin API] curl http://localhost:1610/materialized-datasets/acme/eth_mainnet/versions/1.0.0 ``` ::: `ampctl` prints the deployment's state and each table's progress: ``` ID: 1 Status: COMPLETED Kind: Raw Dataset: acme/eth_mainnet@1.0.0 tables: blocks: files_count: 1 total_size_bytes: 63.25 KiB networks: mainnet: start_block: 24000000 current_block: 24000099 block_timestamp: 1765585559 delay_seconds: 28214152s (47 weeks) end_block: 24000099 logs: files_count: 1 total_size_bytes: 2.15 MiB networks: mainnet: start_block: 24000000 current_block: 24000099 block_timestamp: 1765585559 delay_seconds: 28214152s (47 weeks) end_block: 24000099 transactions: files_count: 1 total_size_bytes: 4.08 MiB networks: mainnet: start_block: 24000000 current_block: 24000099 block_timestamp: 1765585559 delay_seconds: 28214152s (47 weeks) end_block: 24000099 ``` This deployment reached its end block, and `delay_seconds` is how old those blocks are. A deployment without an end block keeps following the chain, and `delay_seconds` drops to seconds once it catches up. Revisions like `latest` work too. `--json` prints the full response, below. ## What a status covers [Deploying](/managing-amp/datasets#deploy-a-dataset) a revision schedules a parent job, which stands for the deployment, and two jobs under it: the **materialization**, which writes the tables, and **garbage collection**, which periodically deletes the files the tables no longer use. The status reports all three: ```json { "id": 1, "idempotency_key": "1f88bf7bcbcf5172888c5833dec8d43bb6768c5fed1985c1e79fda5c9cc91410", "status": "COMPLETED", "materialization": { "job_id": 2, "status": "COMPLETED", "progress": { "kind": "materialize-raw", "tables": { "blocks": { "networks": [ { "network": "mainnet", "start_block": 24000000, "current_block": 24000099, "block_timestamp": 1765585559, "end_block": 24000099, "delay_seconds": 28214385 } ], "files_count": 1, "total_size_bytes": 64771 } } } }, "garbage_collection": { "job_id": 3, "status": "COMPLETED", "locations_pending": 0, "files_collectable": 0, "files_waiting": 0 } } ``` (`progress` is cut to one table.) | Field | Description | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | The deployment's ID, which deploying returned. It stays the same for the deployment's life. | | `idempotency_key` | A hash that identifies the deployment's jobs. Deploying the same revision again while this key is active returns this deployment. | | `status` | The deployment's status, as a whole. See [Statuses](/managing-amp/dataset-status#statuses). | | `detail` | Why the deployment failed, when its status is `ERROR` or `FATAL`. | | `materialization.job_id` | The ID of the job that writes the tables. Use it with [`ampctl job`](/managing-amp/jobs). | | `materialization.status` | That job's status. | | `materialization.progress` | How far each table got. See [Progress](/managing-amp/dataset-status#progress). | | `materialization.detail` | Why the materialization failed, when it did. | | `garbage_collection.job_id` | The ID of the garbage collection job. | | `garbage_collection.status` | That job's status. It runs periodically, so it cycles through `SCHEDULED`, `RUNNING`, and `COMPLETED`. | | `garbage_collection.locations_pending` | How many table locations have files waiting to be deleted. | | `garbage_collection.files_collectable` | How many files its next run will delete. A count that keeps growing between requests means garbage collection is falling behind. | | `garbage_collection.files_waiting` | How many files the tables no longer use, but that queries may still be reading, so they're kept a while longer. | | `garbage_collection.next_collectable_at` | When the first of those files can be deleted, in Unix seconds. Only present when `files_waiting` isn't `0`. | | `garbage_collection.detail` | Why garbage collection failed, when it did. | `ampctl dataset status` shows the deployment's ID, status, and error, and the materialization's progress. The idempotency key, the job IDs, and what garbage collection has left are only in `--json` and the Admin API. `ampctl dataset events` lists the jobs with their IDs (see [See a deployment's events](/managing-amp/datasets#see-a-deployments-events)). ## Progress Progress is computed when you ask for it, from the files the materialization has written. Until it has written to at least one table, there's no progress: `ampctl` prints `Progress: (nothing written yet)` and `Kind: (unknown)`, and the JSON leaves out `progress`. You also see this on a dataset with data, once [another dataset with the same manifest](/managing-amp/datasets#register-a-manifest-under-a-second-name) is deployed. Its shape depends on the dataset's kind, which its `kind` field names: `materialize-raw`, `materialize-derived`, or `materialize-phaser` (`Raw`, `Derived`, or `Phaser` in `ampctl`'s `Kind`). Every kind reports each table under `tables`, by name, with: | Field | Type | Description | | ------------------ | ------- | ------------------------------------------------------------------ | | `files_count` | integer | How many Parquet files the table has. | | `total_size_bytes` | integer | Their total size, in bytes. `ampctl` shows it in KiB, MiB, or GiB. | ### Raw datasets Each table lists its progress per network under `networks`: | Field | Type | Description | | ----------------- | --------------- | -------------------------------------------------------------------------------------------------- | | `network` | string | The network, like `mainnet`. | | `start_block` | integer | The lowest block written. | | `current_block` | integer | The highest block written. | | `block_timestamp` | integer or null | When `current_block` was produced, in Unix seconds. | | `delay_seconds` | integer | How long ago that was: how far behind the chain the table is. Only present with `block_timestamp`. | | `end_block` | integer or null | The block the deployment stops at, or `null` if it follows the chain. | `start_block` and `current_block` are the extent of what's written, not a promise that every block between them is: while extracting in parallel, a table can have gaps that later fill in. ### Derived datasets A derived table can combine several networks, so its progress is a time rather than a block: ```json { "kind": "materialize-derived", "tables": { "transfers": { "networks": ["mainnet"], "watermark_timestamp": 1793369388, "delay_seconds": 12, "files_count": 62, "total_size_bytes": 904523118 } } } ``` | Field | Type | Description | | --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | `networks` | array of strings | The networks its data covers. | | `watermark_timestamp` | integer or null | The time, in Unix seconds, up to which every network is written. With several networks, it's the one furthest behind. | | `delay_seconds` | integer | How long ago `watermark_timestamp` was. Only present with it. | ### Phaser datasets [Phaser](/providers/phaser) datasets count positions rather than blocks, and have no timestamps, so no delay: | Field | Type | Description | | ------------------ | ------- | ----------------------------- | | `network` | string | The network. | | `start_position` | integer | The lowest position written. | | `current_position` | integer | The highest position written. | ## Statuses The deployment and each of its jobs have one of the [job statuses](/managing-amp/jobs/lifecycle): `SCHEDULED`, `RUNNING`, `COMPLETED`, `ERROR`, `FATAL`, `CANCELLED`, `STOP_REQUESTED`, `STOPPING`, or `STOPPED`. In short: * `RUNNING`: materializing. A deployment without an end block stays `RUNNING` as it follows the chain. * `COMPLETED`: the materialization reached its end block. * `ERROR`: it failed, and will be retried (see [Retries](/managing-amp/jobs/retries)). * `FATAL`: it failed for good, or ran out of retries. * `STOPPED`: you [stopped](/managing-amp/datasets#stop-a-deployment) it. When the deployment or its materialization is `ERROR` or `FATAL`, `ampctl` adds the error: ``` Error detail: error_message: provider request timed out ``` ## Errors | Error | Cause | Fix | | ---------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------- | | `dataset not found: acme/eth_mainnet@1.0.0` (`404`) | The dataset or revision isn't registered. | Check it with `ampctl dataset versions acme/eth_mainnet`. | | `materialized dataset not found: acme/eth_mainnet@1.0.0` (`404`) | The revision is registered, but was never deployed. | [Deploy](/managing-amp/datasets#deploy-a-dataset) it. | The [Admin API reference](/managing-amp/admin-api/materialized-datasets#get-a-materializations-status) lists every field and error.