---
title: "Check TLS certificate expiry from CT logs"
method: POST
path: "/v1/metered/cert-expiry"
tags: ["Domain and infrastructure"]
---

# Check TLS certificate expiry from CT logs

`POST /v1/metered/cert-expiry`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/metered/cert-expiry`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Reads Certificate Transparency logs and reports days remaining on the certificate most likely deployed right now (the unexpired entry with the latest not_before). Relevant as CA/Browser Forum rules shrink standard certificate lifetimes toward 47 days by 2029.

**Billing.** $0.05 per successful call. Failed calls are never billed. Charged against prepaid credits when the balance covers it, otherwise metered to your card. Threat Intelligence subscribers and AWS Marketplace bundle customers call this at no extra charge.

**Note.** `cert_found: true` with `days_remaining: null` and `risk_level: CRITICAL` means historical certificates exist but none are currently valid -- distinct from `cert_found: false`, which means the domain has never appeared in CT logs.

## Request body

- object
  - `domain` string, required: Domain to check. A leading `www.` is stripped.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `domain` string: The normalised domain.
    - `cert_found` boolean: True when CT logs hold any certificate for the domain.
    - `expires_at` string, nullable: Expiry timestamp. null when no live certificate.
    - `days_remaining` integer, nullable: Days until expiry. null when no live certificate.
    - `risk_level` 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'null', nullable: CRITICAL at 7 days or fewer, HIGH at 14, MEDIUM at 30, otherwise LOW. null when no certificates exist at all.
    - `issued_at` string, nullable: Issue timestamp of the live certificate.
    - `recommendation` string: Plain-English action.
    - `checked_at` string, date-time: ISO 8601 UTC timestamp of when this check ran.

## Other responses

- `400`: `domain` is missing or contains no '.'.
- `401`: Missing or invalid API key.
- `402`: No credits and no active subscription. The response carries `topup_url`.
- `405`: Wrong HTTP method. Every endpoint is POST.
- `502`: Certificate Transparency log lookup failed.

---

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