TLS versions, cipher suites and session resumption

GET

/analytics/tls

curl --request GET \
  --url 'https://api.nsin.ir/analytics/tls?domain=example.com&period=3h' \
  --header 'Authorization: Bearer <token>'

• Production

What your visitors negotiate with the edge. Every count here is restricted to TLS-terminated requests, so plain-HTTP traffic never enters the totals — a domain redirecting :80 to :443 does not read as though a slice of its visitors used no TLS at all.

pct in versions is a share of all TLS requests. pct in ciphers is a share of the returned suites only: the list is capped at the top 12, and the shares are normalised over that list so they still add up to 100%.

This is the visitor-to-edge leg only. The edge-to-origin handshake is not reported here.

Authorizations

• bearerAuth
• apiKeyAuth

Parameters

Query Parameters

domain

required

string

The domain name (for example example.com). These endpoints take the domain as a query parameter rather than a path segment.

Example

example.com

period

string

default: 24h

Allowed values: 3h 6h 12h 24h 7d 30d

Time window, ending now. Buckets are hourly up to 24h and daily for 7d and 30d. An unrecognised value falls back to 24h.

hostname

string

Narrow to one subdomain. Matches the exact host, any subdomain of it, or a bare label — so example.com matches api.example.com, and api matches api.example.com, but exam matches neither.

path

string

Narrow to a URL path prefix.

Responses

200

TLS mix for the period.

Media type application/json

object

summary

object

requests

TLS-terminated requests in the period.

integer

resumed

Requests whose TLS session was resumed rather than negotiated afresh.

integer

resumption_rate

resumed / requests, as a percentage; 0 when there were no TLS requests.

number

versions

Array<object>

object

version

Negotiated version, e.g. TLSv1.3.

string

requests

integer

pct

Percentage share of all TLS requests.

number

ciphers

Top 12 cipher suites, most used first.

Array<object>

object

cipher

Negotiated cipher suite, e.g. TLS_AES_128_GCM_SHA256.

string

requests

integer

pct

Percentage share of the returned suites

number

Example ^generated

{
  "summary": {
    "requests": 1,
    "resumed": 1,
    "resumption_rate": 1
  },
  "versions": [
    {
      "version": "example",
      "requests": 1,
      "pct": 1
    }
  ],
  "ciphers": [
    {
      "cipher": "example",
      "requests": 1,
      "pct": 1
    }
  ]
}

400

The domain query parameter is missing.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example missing

{
  "error": "domain is required"
}

401

Missing, malformed, revoked or expired API key — or the owning account is inactive.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example invalidKey

{
  "error": "invalid API key"
}

403

The domain’s plan does not include the feature this endpoint needs (monitoring for most sections, logs for raw and top-N request data).

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example limited

{
  "error": "rate limit exceeded"
}

503

The analytics backend is temporarily unreachable. Retry; no data is lost.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example unavailable

{
  "error": "analytics unavailable"
}