sweeps

Poll a sweep job; paginate results when done

Poll a submitted sweep. While queued/running, returns status only; when done, returns a page of results (same row shape as /v1/certificates/search, plus per-row match_class and match_reason annotations: match_class ∈ first_party / lookalike_candidate / third_party_integration / substring_collision / shared_hosting; match_reason names the rule and token that fired); when failed, returns the structured error (e.g. sweep_timeout → narrow cn/san_contains or add issuer/time windows and resubmit — the post-match attribution filters will not help). A done result with truncated: true also carries next_cursor — submit a new sweep with the same filters plus resume_token: <next_cursor> to page past the result cap (keyset continuation, no gaps or duplicates).

status is terminal (done/failed) if and only if finished_at is set — the two can never disagree, so a response is never running with a finish timestamp already recorded. The timing block breaks the latency down into queued_ms (broker wait, usually dominant), query_ms (the engine scan alone), execution_ms (worker wall clock) and total_ms (submit → terminal, what a polling caller waits).

get/v1/sweeps/{job_id}

Request

  • Base URL: https://api.ctindex.io
  • URL: https://api.ctindex.io/v1/sweeps/{job_id}
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

job_idstring uuid required

Query parameters

pageinteger
limitinteger
cursorstring nullable

NOT supported here — accepted only so a mistaken cursor walk fails loudly (422) instead of being silently served as page 1. Sweep results are an immutable materialized set, so page/limit paging is already gap-free; and next_cursor on this route is a sweep RESUME token for a new submission, not a page cursor.

match_classstring nullable

Filter results to rows with this match_class only (post-materialization view filter — does not change result_count or next_cursor). One of: 'first_party', 'lookalike_candidate', 'third_party_integration', 'substring_collision', 'shared_hosting'. Null-class rows (persisted before the taxonomy existed) are excluded when this filter is set.

match_class_filterstring nullable

Comma-separated view filter applied before page/limit pagination. Allowed values: first_party, lookalike_candidate, third_party_integration, substring_collision, shared_hosting. Defaults to the normalized filter persisted at submit time.

Cookies

ctix_sessionstring nullable

Response

Successful Response

job_idstring uuid required
statusstring required

queued | running | done | failed. Terminal (done/failed) if and only if finished_at is non-null — the two can never disagree (GH #267).

filtersobject required
created_atstring date-time required
started_atstring date-time nullable
finished_atstring date-time nullable

Set if and only if status is terminal (done/failed). A response never carries a finish timestamp while reporting queued/running.

errorobject nullable
result_countinteger nullable
truncatedboolean
result_capinteger required
next_cursorstring nullable

Present only when status='done' AND truncated=true: an opaque keyset continuation token. Submit a NEW sweep with the same filters plus resume_token: <next_cursor> to fetch the next (up to) result_cap rows with no gaps or duplicates. Repeat until a sweep finishes with truncated=false.

pageinteger nullable
limitinteger nullable
has_moreboolean nullable

Changes

No recorded changes to this operation across all 1 revision of this API.