# Which Vast.ai API key should the monitor use, and where does it go?

Put the key in the account connection, not in the Machine ID field. A read-only monitor needs permission to view machines and earnings. Transfers and listing changes are write permissions and should stay off that key. A refused report leaves the total unknown.

- Canonical: https://iotahome.site/en/learn/vast-api-key-read-only-monitoring
- Publisher: IOTA Watch
- Topics: Vast.ai
- Published: 2026-10-24
- Updated: 2026-10-24

## At a glance

Connect the hosting account with a read-only key, then name the machine with its Machine ID. A client-instance key, a transfer permission, or a list/unlist permission is outside what this key needs. Connecting the key does not mean Vast has verified the machine.

## Key in the connection, number in Machine ID

Create a key with machine_read and billing_read only, and put it in the account connection. Copy the Machine ID from the Host machines page. Leave write permissions off.

## Key permissions and whether the monitor needs them

| Permission category | What Vast says it can do | Give it to this monitor key? |
| --- | --- | --- |
| machine_read | View machines and reports | Yes. Without it the machine list is not visible |
| billing_read | View invoices and earnings | Yes. Earnings are Show Earnings in this category |
| billing_write | Transfer credit | No. That is not a read |
| machine_write | List, unlist, maintenance, cleanup | No. The monitor does not operate the machine for you |
| instance_read / instance_write | View or create client instances | Do not substitute a client key for a host key |

The monitor needs a read-only key on the hosting side, stored in the account connection on the [Vast.ai monitor](https://iotahome.site/en/projects/vast). The Machine ID field accepts only the machine number. A key made to launch client instances, or a key that can transfer credit or list and unlist machines, is the wrong key for this read.

## How to read the permissions page

Vast grants permissions by category. machine_read covers viewing machines and reports. billing_read covers invoices and earnings, including Show Earnings. billing_write is Transfer Credit. machine_write includes listing, unlisting, maintenance, and cleanup. instance_read and instance_write are client instances, not the host machine list.

The permissions page names actions. It does not pin every URL. If a path you expected is absent, that is not a reason to enable transfers or listing changes.

## What to check after connecting

- The machine list shows your Machine ID, and the GPU name matches the machines page.

- A day total appears only when all four lines are present. One gap, or a report that does not come back, leaves the total unknown.

- The account balance is not copied onto this machine. See [revenue and balance](https://iotahome.site/en/learn/vast-host-revenue-vs-balance).

## What to do next

- No machines visible: add machine_read, and confirm the key belongs to the hosting account rather than a client account.

- Machines visible, earnings missing: add billing_read. Do not enable billing_write.

- To change price or unlist: use the Host machines page, or a different key that has machine_write. This read-only key does not do that. Occupancy stays in [offers and contracts](https://iotahome.site/en/learn/vast-gpu-occupancy-and-offers).

## Illustrative case

Illustrative, not a live permission trial: enable only machine_read and billing_read. The machine list returns id 12001, and the four lines 1.20, 0.30, 0.10, and 0.05 sum to 1.65 USD. If earnings are refused this time, the total becomes unknown while the machine record can remain. Do not rewrite it as 0, and do not substitute a 40 USD balance.

## Limits

A connected key means this read was accepted. It does not mean Vast has verified the machine, and it does not mean rent will be paid out. Do not publish the key. The agent cannot start or stop Vast rentals with it; the agent controls Train at Home on a Mac only. Crash analysis is free.

## Common questions

### Can I paste the API key into the Machine ID field?

No. The Machine ID is the machine number. The key belongs only in the Vast account connection, where the server uses it to read your machines and earnings. Do not put the key in a public note, a machine name, or a comment on this guide.

### The permissions page does not name the machine-earnings path. Which boxes do I enable?

Follow the action names on the permissions page: machine_read for viewing machines, and Show Earnings inside billing_read for earnings. The page does not pin every URL. If machines or earnings are still missing after you connect, add only those read categories. Do not also turn on billing_write or machine_write.

### The key works, but the day total is unknown. Is the machine broken?

Not necessarily. Unknown means the four lines for this machine are incomplete, or the earnings report did not come back this time. Offline, unverified, or no current rental are separate facts on the machines page. Do not rewrite unknown as 0, and do not replace it with the balance.

## Sources and implementation

- [Vast.ai API permissions](https://docs.vast.ai/api-reference/permissions)
- [Vast.ai hosting overview](https://docs.vast.ai/host/hosting-overview)