---
title: "Get host history for a certificate"
method: GET
path: "/v3/threat-hunting/certificate/{certificate_id}/observations/hosts"
tags: ["Threat Hunting", "Adversary Investigation"]
---

# Get host history for a certificate

`GET /v3/threat-hunting/certificate/{certificate_id}/observations/hosts`

## Request

- Base URL: `https://api.platform.censys.io`
- URL: `https://api.platform.censys.io/v3/threat-hunting/certificate/{certificate_id}/observations/hosts`
- Auth: HTTP bearer

Retrieve the historical observations of hosts associated with a certificate. Use this endpoint to see every host that has presented a given certificate over time, so you can build a timeline and find other infrastructure using it.<br><br>Certificate history is also visible to Adversary Investigation users in the Platform UI on the [certificate timeline](https://docs.censys.com/docs/platform-threat-hunting-use-cert-history-to-build-better-detections#/).<br><br>You can define a specific time frame of interest. If you do not specify a time frame, this endpoint will search the historical dataset that is available to your account.<br><br>For workspaces with a history limit, the API returns observation ranges that overlap the allowed history window. The window starts at 00:00 UTC the allowed number of days ago and ends at the time of the request. Ranges are returned in full, with their original start and end times, even if they extend outside the window.<br><br>You may also filter results by port and transport protocol.<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module. This endpoint costs one credit per page of results.

## Path parameters

- `certificate_id` string, required: SHA-256 hash of the certificate

## Query parameters

- `organization_id` string, uuid, required: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
- `start_time` string: Only show ranges ending at or after this time (ISO 8601)
- `end_time` string: Only show ranges starting at or before this time (ISO 8601)
- `port` integer: The port to filter by
- `protocol` string: The application protocol to filter by
- `page_token` string: Pagination token from previous response to retrieve next page of results
- `page_size` integer: Number of results per page. Maximum 100, defaults to 100 if not specified

## Headers

- `X-Organization-ID` string, uuid: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

## Response `200`

A list of host observations for the certificate

- ResponseEnvelopeHostObservationResponse
  - `result` HostObservationResponse
    - `next_page_token` string
    - `ranges` HostObservationRange[], nullable, required
      - `end_time` string, date-time, required
      - `ip` string, required
      - `port` integer, required
      - `protocols` string[], nullable, required
      - `start_time` string, date-time, required
      - `transport_protocol` string, required
    - `total_results` integer, required

## Other responses

- `400`: Bad request
- `401`: Request does not contain a valid Authorization token
- `403`: User does not have permission to access this data
- `404`: Resource not found
- `500`: Internal server error

---

[API](https://skmtc.dev/censys/apis/censys-platform-api.md) - [All operations](https://skmtc.dev/censys/apis/censys-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/censys/apis/censys-platform-api/revisions/ec1686b0a36a?raw)