---
title: "Get a host's current state"
method: GET
path: "/v1/hosts/{hostname}"
tags: ["Hosts"]
---

# Get a host's current state

`GET /v1/hosts/{hostname}`

## Request

- Base URL: `https://api.peppolstatus.com`
- URL: `https://api.peppolstatus.com/v1/hosts/{hostname}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Current role, verdict, network attribution (IPs/PTR), TLS certificate and operating provider for a host. `?at=` returns point-in-time state. `profile` carries the crawled software identity of the host's registrable domain when one is publishable (curated, or extraction confidence 0.8+ — then unverified).

## Path parameters

- `hostname` string, required

## Query parameters

- `at` string, date-time

## Response `200`

The host's state.

- HostView: A host's current (or point-in-time) state.
  - `hostname` string, required
  - `role` 'SMP' | 'AP' | 'null', nullable, required
  - `verdict` 'up' | 'degraded' | 'down' | 'unresolvable' | 'null', nullable, required: Rolled-up host state (issue #310): a per-location `Verdict` (`up`/`degraded`/`down`) plus the derived `unresolvable` — a hostname that has NEVER resolved in DNS. `unresolvable` is neutral/informational, NOT an outage. null when unknown.
  - `network` HostNetwork, required
    - `ips` string[], required
    - `ptr` string, nullable, required
  - `cert` HostCert, nullable, required
    - `fingerprint` string, required
    - `subject` string, required
    - `issuer` string, required
    - `not_before` string, date-time, required
    - `not_after` string, date-time, required
    - `days_to_expiry` integer: Whole days from the response instant to `not_after`, floored; negative once the certificate has expired (issue #519). Derived server-side.
    - `expiry_status` 'ok' | 'expiring' | 'expired': Derived TLS-expiry state (issue #519): `expired` once `not_after` is past, `expiring` within 30 days of now, else `ok`. A tighter near-term window additionally raises a `host_tls_cert_expiring`/`host_tls_cert_expired` anomaly.
  - `provider` HostProviderInfo, nullable
    - `key` string, required
    - `trade_name` string, required
    - `legal_name` string, nullable, required
    - `country` string, nullable, required
    - `ap_key` string, nullable: The provider's access-point directory key for the console's /providers/{key} link (the `key` field above is the natural key, which that route does not resolve); null when no seat of the provider is a member of any directory entry. Optional: an edge-cached /v1/hosts response minted before this field existed omits it.
  - `profile` HostProfileView: Crawled software identity of the host's registrable domain (eTLD+1), so every `smp.acme.com` / `ap.acme.com` shares one profile. Only rows that pass the surfacing rule appear: a curator confirmed the identity (`curated: true`), or extraction confidence reached 0.8 — then the row is AUTO-GENERATED and UNVERIFIED and must be labelled as such.
    - `domain` string, required: The registrable domain the profile describes.
    - `status` 'identified' | 'infrastructure', required: `identified` — the domain's own company/product. `infrastructure` — a multi-tenant platform the host RUNS ON (read it as "runs on X", never "is X").
    - `company_name` string, nullable, required
    - `product_name` string, nullable, required
    - `tagline` string, nullable, required
    - `category` string, nullable, required
    - `confidence` number, nullable, required: Extraction confidence 0..1; null for a curated row with no stored score.
    - `curated` boolean, required: True when a curator confirmed the identity. False means auto-generated and unverified — annotate, never assert.
    - `screenshot_url` string, nullable, required: Same-origin path to the homepage screenshot (`/v1/hosts/asset/{domain}/screenshot.jpg`, free tier); null when none captured.
    - `crawled_at` string, date-time, nullable, required
  - `seats` HostSeat[]: The Seat(s) this host currently operates (from seat sightings). Each seat's `seat_id` is the participant.ap_seat_id value linking the host to the participants it serves.
    - `seat_id` string, required
    - `role` 'SMP' | 'AP', required
    - `provider` SeatProvider, required: Embedded provider for a seat, verified mapping or unverified CN fallback.
      - `slug` string, nullable, required
      - `name` string, nullable, required
      - `country` string, nullable, required
      - `verified` boolean, required
      - `key` string, nullable: The curated provider's OpenPeppol registry natural key, when the mapping carries one. It decides whether the seat's operator and a host's owner are the same party; it is not a /v1/aps route key and not the slug. Optional: absent on a cached response minted before the field shipped.

## Other responses

- `400`: `at` is not a valid ISO 8601 timestamp.
- `404`: No such host is known.

---

[API](https://skmtc.dev/peppolstatus/apis/peppolstatus-api.md) · [All operations](https://skmtc.dev/peppolstatus/apis/peppolstatus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/peppolstatus/apis/peppolstatus-api/revisions/7e74fb32f23c?raw)