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

# Instance metadata service

> Access server metadata from within your bare metal servers using the instance metadata service

<Warning>
  The metadata service is not yet available in the **SAO** and **SAN3** regions. Support for these regions will be added in a future update.
</Warning>

The instance metadata service provides a way for your bare metal servers to access their own metadata — such as hostname, IP addresses, network configuration, storage layout, and tags — through a local HTTP endpoint. It is available from within any running Latitude.sh bare metal server.

## How it works

The metadata service runs on a link-local IP address (`169.254.169.254`) that is only reachable from within the server itself. Before querying metadata, you request a short-lived session token. You can then retrieve all metadata as a single JSON object or query individual fields by path.

## Quick start

<Steps>
  <Step title="Get a session token">
    Request a session token with a TTL (time-to-live) in seconds. The token is returned in the response body.

    ```bash theme={null}
    TOKEN=$(curl -s -X PUT "http://169.254.169.254/metadata/v1/api/token" \
      -H "X-Metadata-Token-TTL-Seconds: 3600")
    ```
  </Step>

  <Step title="Retrieve all metadata as JSON">
    Use the token to fetch the full metadata object:

    ```bash theme={null}
    curl -s "http://169.254.169.254/metadata/v1/metadata.json" \
      -H "X-Metadata-Token: $TOKEN" | jq
    ```
  </Step>

  <Step title="Query individual fields">
    You can also retrieve specific fields by path:

    ```bash theme={null}
    # Get the server hostname
    curl -s "http://169.254.169.254/metadata/v1/hostname" \
      -H "X-Metadata-Token: $TOKEN"

    # Get the public IPv4 address
    curl -s "http://169.254.169.254/metadata/v1/public_ipv4" \
      -H "X-Metadata-Token: $TOKEN"

    # Get the full network configuration
    curl -s "http://169.254.169.254/metadata/v1/network" \
      -H "X-Metadata-Token: $TOKEN" | jq
    ```
  </Step>
</Steps>

<Note>
  The metadata service is only accessible from within the server. It cannot be reached from the public internet or from other servers.
</Note>

## Available fields

| Field              | Description                                                                                                                |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `instance_id`      | Unique server identifier                                                                                                   |
| `hostname`         | Server hostname                                                                                                            |
| `local_ipv4`       | Private IPv4 address                                                                                                       |
| `public_ipv4`      | Public IPv4 address                                                                                                        |
| `public_ipv6`      | Public IPv6 address                                                                                                        |
| `region`           | Region code (e.g., `SAO`, `DAL`)                                                                                           |
| `plan`             | Server plan slug                                                                                                           |
| `operating_system` | Operating system slug                                                                                                      |
| `userdata`         | User data script content                                                                                                   |
| `tags`             | Tags attached to the server                                                                                                |
| `network`          | Network interfaces and DNS configuration (see [full schema](/api-reference/metadata-service#response-schema))              |
| `storage`          | Disk information (see [full schema](/api-reference/metadata-service#response-schema))                                      |
| `ssh_keys`         | SSH public keys deployed to the server                                                                                     |
| `vendor`           | Vendor-specific metadata such as project and team IDs (see [full schema](/api-reference/metadata-service#response-schema)) |

## Common use cases

* **Network configuration** — read interface details and IPs to configure networking at boot
* **Dynamic inventory** — register the server in Ansible, Consul, or other inventory systems using its own metadata
* **Cloud-init scripts** — combine with [user data](/servers/user-data) to build dynamic configuration scripts that adapt to the server's environment
* **Application configuration** — inject region, hostname, or tags into your application's runtime config

For the complete schema, all available paths, and authentication details, see the [Instance Metadata Service API reference](/api-reference/metadata-service).