Retrieve evaluation results
Retrieve domains and evaluation results for a Business or MSP organization. The token requires reports:read and determines the organization; organization parameters are rejected. Only GET is accepted; other methods return 405 and Allow: GET. Organization source IP restrictions apply. Responses include Cache-Control: no-store.
Unknown or repeated parameters return 400 INVALID_PARAMETER. The pre-authentication source IP limit is 120 requests per minute. The audit log and evaluation results APIs share 60 requests per minute per token. Excess requests return 429 RATE_LIMITED with Retry-After in seconds. Every successful read records api_token.reports_read.
GET /api/v1/domains
Returns organization domains, including archived domains, with their latest evaluation summary. latest_report is null if no evaluation exists. Results are ordered by created_at, then domain_id.
| Parameter | Description |
|---|---|
cursor | Previous next_cursor, bound to the organization and endpoint. |
limit | Integer 1–1000; default 100. |
| Field | Description |
|---|---|
schema_version | Public schema version (1.0) |
domain_id | Domain ID |
name | Domain name |
schedule | MANUAL / DAILY / WEEKLY |
active_requested | Whether active checks were requested |
archived_at | Archive time, or null |
created_at | Registration time |
latest_report | Latest evaluation summary, or null; includes report_id, generated_at, score, grade, grade_withheld and coverage. |
curl
curl --get -H "Authorization: Bearer $SPECTRA_REPORTS_TOKEN" "https://api.spectra-app.net/api/v1/domains"GET /api/v1/reports
Returns evaluation summaries across the organization for BI or SIEM ingestion. since and until filter generated_at inclusively. Timestamps require seconds and a timezone; fractional seconds may have up to millisecond precision, for example 2026-09-01T00:00:00Z. Invalid times or since after until return 400 INVALID_TIME. Results are ordered by generated_at, then report_id.
| Parameter | Description |
|---|---|
domain_id | Filter by domain ID. Another organization's ID returns an empty result. |
since | Inclusive generated_at start time. |
until | Inclusive generated_at end time. |
cursor | Previous next_cursor, bound to the organization and endpoint. |
limit | Integer 1–1000; default 100. |
| Field | Description |
|---|---|
schema_version | Public schema version (1.0) |
report_id | Evaluation result ID |
domain_id | Domain ID |
domain | Domain name |
generated_at | Evaluation generation time |
score | Score, or null when withheld |
grade | Grade, or null when withheld |
grade_withheld | Whether score and grade are withheld |
coverage | Coverage (0–100%) |
active_authorized | Whether active checks were authorized |
calculation_version | Scoring formula version; null for older results |
curl
curl --get -H "Authorization: Bearer $SPECTRA_REPORTS_TOKEN" --data-urlencode "since=2026-09-01T00:00:00Z" "https://api.spectra-app.net/api/v1/reports"For incremental ingestion, restart 10 minutes before the previous end time and deduplicate by report_id. A result may become available after its generation time.
GET /api/v1/reports/{id}
Returns one evaluation result as JSON. lang selects the language of check display text. Missing IDs and IDs belonging to another organization both return 404 NOT_FOUND.
| Parameter | Description |
|---|---|
lang | ja or en; default ja. |
include | Only evidence is accepted; includes collected evidence. |
The response adds these fields to the summary fields:
| Field | Description |
|---|---|
engine_version | Evaluation engine version |
report_schema_version | Stored format version |
lang | Display text language |
categories | Category results; null for older results without this information |
checks | Check results; null for older results without a check list |
findings | Individual findings |
assets | Observed assets |
collection | Collection issues; null for older results without this information |
evidence | Collected evidence, present only with include=evidence. |
Each categories entry contains category, score and coverage. Entries follow this order: dns_mail, exposure, future, impersonation, leak, reputation, supply_chain, tls_cert, web. Categories that did not exist when the evaluation was performed are omitted, so older results may have fewer than nine entries. Identify entries by their category value rather than by their position or the number of entries. A recorded category that could not be observed remains in the array with a null score.
checks entries contain id, category, result, status, severity, impact, title, action_title, summary, why, remediation, subjects and evidence_ids. The result is fail, unobserved, not_applicable or pass. Failures are ordered by severity, impact and ID; other groups follow in result order and then ID order. Display text follows lang. Status is fail, warn, pass, not_applicable, not_observable or not_collected. Severity is critical, high, medium, low or info. Impact is the score increase from fixing only that check, or null when inapplicable. Subjects contain subject and status; evidence_ids identify collected evidence.
findings entries contain check_id, status, severity, subject, summary, evidence_ids and detail; summary is in English; subject and detail may be null. assets entries contain kind, value and source; kind examples are host, ip, asn and prefix. collection contains errors and skipped. evidence entries contain id, collector, kind, subject, collected_at and raw. The raw field contains source data; request include=evidence only when needed.
Pagination and scores
JSON lists return data and next_cursor. With Accept: application/x-ndjson, each line is one data element. Only responses with another page include X-Next-Cursor and Link: …; rel="next". The signed cursor is opaque. Send it with the same filters. Cursors from another organization, another endpoint or the audit log API return 400 INVALID_CURSOR. The limit is an integer from 1 to 1000, defaulting to 100; out-of-range values return 400 INVALID_LIMIT.
When coverage is below 50%, score and grade are null and grade_withheld is true. Coverage is always returned. This matches the product display and prevents scores from results with substantial collection gaps being used without their context. Grades range from A to F.