# Refresh asset metadata

## Refresh asset metadata

Metadata refreshes update off-chain asset metadata.

<mark style="color:blue;">Read more about asset metadata.</mark>

This <mark style="color:blue;">page</mark> contains code samples that explain how to use the metadata refresh API.

### Use cases[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#use-cases) <a href="#use-cases" id="use-cases"></a>

Metadata refreshes help games:

* Support game play mechanics that rely on metadata such as levelling up characters, crafting and merging
* Refine the game balance
* Refine and correct game content such art and copy
* Delay reveals of primary sales
* Improve search discoverability through metadata

### Requirements[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#requirements) <a href="#requirements" id="requirements"></a>

In order for a refresh to be successful, first:

* Create and deploy the <mark style="color:blue;">Metadata API</mark>, as it's the source of truth for asset metadata
* For reveals, update your Metadata API only once the asset is ready to be revealed. The flow for reveals would be something like:
  * Mint an asset
  * Once ready to reveal, update the Metadata API with the properties to be revealed
  * Refresh metadata for the assets to be revealed
* Ensure your Metadata API availability is aligned with the requirements. The metadata refresh service will concurrently request metadata for each asset from your Metadata API and requires a response time of less than 3 seconds per request in order to successfully update the metadata for that asset.
* If the request to the Metadata API fails to return a valid response, that particular asset will be <mark style="color:blue;">marked as failed.</mark>
* The request to the Metadata API will be retried 2 times (with an exponential backoff function timing each retry) only if the Metadata API returns one of the following HTTP status codes:
  * 429 Too Many Requests
  * 503 Service Unavailable

### API[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#api) <a href="#api" id="api"></a>

Endpoints related to metadata refreshes are denoted via the url resource `/metadata-refreshes`.

The expected maximum time (estimate) to complete a refresh is approximately 48 hours. Updated metadata values will only be reflected in downstream systems e.g. marketplaces once the refresh for that asset is complete.

#### Authentication[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#authentication) <a href="#authentication" id="authentication"></a>

Metadata refresh endpoints are protected via authentication - only the project owner will be able to call these endpoints.

The following headers are required for project owner authentication:

* `x-imx-eth-address` - the Ethereum address of the project owner making the request
* `x-imx-eth-signature` - the signature generated by the project owner
* `x-imx-eth-timestamp` - the timestamp used to generate the signature

<mark style="color:blue;">View how to generate project owner authentication headers.</mark>

#### Requesting a metadata refresh[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#requesting-a-metadata-refresh) <a href="#requesting-a-metadata-refresh" id="requesting-a-metadata-refresh"></a>

A metadata refresh can be requested by calling:

```
POST /v1/metadata-refreshes
```

and specifying the collection address and IDs of the tokens requiring a refresh:

```
{
  "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d", // required
  "token_ids": ["1", "2"] // required
}
```

The user will receive the following response with a HTTP status code of **202 Accepted**:

```
{
  "refresh_id": "21566bcb-4263-48bb-a495-602ba9a12f2c"
}
```

The `refresh_id` acts as a receipt and confirms that the refresh has been initiated and will be processed. It can be used to query the status of a particular refresh.

Projects can programmatically call the refresh endpoint at a specific time or based on a specific event in their system. There is currently no way to cancel a refresh once requested.

<mark style="color:blue;">View the OpenAPI specification for requesting a metadata refresh.</mark>

#### Viewing the status of a metadata refresh[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#viewing-the-status-of-a-metadata-refresh) <a href="#viewing-the-status-of-a-metadata-refresh" id="viewing-the-status-of-a-metadata-refresh"></a>

The status of a refresh can be queried by using the `refresh_id` with the following endpoint:

```
GET /v1/metadata-refreshes/:refresh_id
```

which will return the following response:

```
{
  "refresh_id": "21566bcb-4263-48bb-a495-602ba9a12f2c",
  "status": "completed",
  "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d",
  "started_at": "2022-08-31T01:59:59.806449Z",
  "completed_at": "2022-08-31T02:00:09.786143Z",
  "summary": {
    "succeeded": 2,
    "failed": 0,
    "pending": 0
  }
}
```

**Status**[**​**](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#status)

The status field of a refresh can be the following values:

* `queued` - the refresh has been requested but no tokens have been processed
* `in_progress` - the refresh has started processing and at least 1 token has been processed
* `completed` - all tokens have been processed

**Summary**[**​**](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#summary)

The summary field of a refresh displays the counts of the status of individual tokens belonging to that refresh:

* `succeeded` - the metadata for this token has been successfully updated
* `failed` - the metadata for this token was not able to be updated
* `pending` - the token has not been processed

Another endpoint is available to <mark style="color:blue;">investigate the reason why the metadata for a particular token could not be updated.</mark>

<mark style="color:blue;">View the OpenAPI specification for metadata refresh status.</mark>

#### Viewing metadata refresh errors[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#viewing-metadata-refresh-errors) <a href="#viewing-metadata-refresh-errors" id="viewing-metadata-refresh-errors"></a>

If 2 non-successful attemps have been made to retrieve the updated metadata values from the <mark style="color:blue;">Metadata API</mark>, that token will be marked as `failed`. A more detailed explanation of why token metadata could not be updated for a particular refresh can be queried with the following endpoint:

```
GET /v1/metadata-refreshes/:refresh_id/errors
```

which will return a paginated list of tokens within that refresh that could not be updated and their respective error details:

```
{
  "result": [
    {
      "token_id": "1",
      "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d",
      "client_token_metadata_url": "https://metadata-api.io/1",
      "client_response_status_code": 404,
      "client_response_body": "404 page not found\n",
      "error_code": "invalid_response_status_code",
      "created_at": "2022-09-06T02:14:04.935946Z"
    }
  ],
  "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMi0wOS0wNlQwMjoxNDowNC45MzU5NDZaIiwiaWQiOiIyYzU2ZDE5Ni1mY2ViLTQ1MzItYmMzOC0zZmZlMTFlOTM4Y2UifQ",
  "remaining": 0
}
```

Each item in the results array represents one failed token for that particular refresh.

* `client_token_metadata_url` - the url which was used to perform the Metadata API request
* `client_response_status_code` - the response status code that was received from the Metadata API
* `client_response_body` - any error details that were provided as a response body by the Metadata API
* `error_code` - describes why the metadata could not be updated

**Error codes**[**​**](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#error-codes)

| Error code                     | Description                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `unable_to_retrieve_metadata`  | The metadata refresh service was unable to get a response from the Metadata API, for example the API timed out |
| `invalid_response_status_code` | The metadata refresh service received a non 200 response code when making a request to the Metadata API        |
| `unable_to_decode_response`    | The response received by the Metadata API was unable to be decoded                                             |
| `token_not_found`              | The token does not exist in our system                                                                         |

<mark style="color:blue;">View the OpenAPI specification for metadata refresh errors.</mark>

#### Getting a list of all metadata refreshes[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#getting-a-list-of-all-metadata-refreshes) <a href="#getting-a-list-of-all-metadata-refreshes" id="getting-a-list-of-all-metadata-refreshes"></a>

Users can fetch a list of all metadata refreshes in order to find a particular `refresh_id`, which can then be used to query the status of a particular refresh:

```
GET /v1/metadata-refreshes
```

The above endpoint will return a list of refreshes ordered by `created_at` , showing the most recent refreshes first.

**Filter by collection address**[**​**](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#filter-by-collection-address)

The endpoint results can also be filtered by using the the query parameter `collection_address`:

```
GET /v1/metadata-refreshes?collection_address=COLLECTION_ADDRESS
```

The response returns a paginated list of refreshes:

```
{
  "result": [
    {
      "refresh_id": "ff52e750-2cc6-4455-b1ae-95a4280e4826",
      "status": "completed",
      "collection_address": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d",
      "started_at": "2022-09-06T02:11:03.065286Z",
      "completed_at": "2022-09-06T02:14:04.945285Z"
    }
  ],
  "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyMi0wOC0zMFQwNzozODoxMS4xMzczMTRaIiwiaWQiOiI2YzhlMDNjNS04ZWYxLTQzNmQtOWNjZS1iM2ExNDdmYzc3NGIifQ",
  "remaining": 0
}
```

<mark style="color:blue;">View the OpenAPI specification for a list of metadata refreshes.</mark>

### Metadata refresh limits[​](https://docs.x.immutable.com/docs/x/asset-metadata-refreshes#metadata-refresh-limits) <a href="#metadata-refresh-limits" id="metadata-refresh-limits"></a>

There are limits on the number of the number of metadata refresh requests made per project, per hour.

* For a particular project, **20** metadata refresh requests can be made per hour
* Up to **1000** tokens can be requested per refresh

Whenever a <mark style="color:blue;">refresh is requested</mark> or when a refresh limit has been reached, the following headers will be returned:

* `x-imx-refreshes-limit` - the amount of refreshes that can be requested per hour
* `x-imx-remaining-refreshes` - the amount of refreshes remaining for the current hour interval
* `x-imx-refresh-limit-reset` - a UNIX timestamp indicating when the limit resets by rolling over into the next hour interval

If the refresh limit has been reached, the user will receive a response with a HTTP status code of **429 Too Many Requests**:

```
{
  "code": "refresh_limit_exceeded",
  "message": "Refresh limit exceeded"
}
```

ADDITIONAL REQUESTS

If you need to perform additional refresh requests, you can <mark style="color:blue;">contact support.</mark>
