Skip to content
Verdict

GET /v1/events
Call GET /v1/events
Price free unscored; with icp_id each scored event bills one score_signal ($0.005)
Scope index:read
Operation id listEvents

What it does

Section titled “What it does”

Events from the index for one firm (firm_id) or for an ICP (icp_id), newest first, optionally filtered by since and types. Without icp_id the call is free and score is null. With icp_id every returned event is scored (score set) and bills one score_signal ($0.005) per scored event (needs decisions:write too); a page with icp_id holds at most 50 events. A score made for the same ICP and event within the last hour is reused and not billed again. min_p filters the returned events on relevant; events below it were still scored and billed. If the balance (or the key’s daily cap) runs out, or the decision model becomes unavailable, part-way through a page, the page stops there: you get the events scored and billed so far, has_more: true and a next_cursor that resumes at the first unscored event. Only when the first event cannot be scored is the error returned (402 insufficient_balance, or 503 decision_unavailable with Retry-After). Cursor-paginated. Scope: index:read.

Example request

Section titled “Example request”

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

Request
curl -X GET 'https://api.askverdict.io/v1/events?firm_id=frm_01JC3Z4Y8R9K2M5N7P1Q3S5T7V&icp_id=icp_01JC3Z4Y8R9K2M5N7P1Q3S5T7V&types=filing%2Cfund_raise&min_p=0.6' \
  -H "Authorization: Bearer $VERDICT_API_KEY"

Example response

Section titled “Example response”

200: A page of events.

200 response
{
  "data": [
    {
      "id": "evt_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
      "type": "filing",
      "firm_id": "frm_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
      "occurred_at": "2026-11-03T21:15:00Z",
      "observed_at": "2026-11-04T02:05:00Z",
      "source": "sec_edgar",
      "source_url": "https://www.sec.gov/Archives/edgar/data/1601234/000160123426000004/xslFormDX01/primary_doc.xml",
      "confidence": 0.97,
      "attributes": {
        "filing_type": "sec_form_d",
        "accession_number": "0001601234-26-000004",
        "title": "Notice of Exempt Offering of Securities"
      },
      "score": {
        "decision_id": "dec_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
        "icp_id": "icp_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
        "relevant": 0.78,
        "act_now": 0.64,
        "window_days": 21,
        "answer": "relevant",
        "reason_code": "event_relevant_and_timely"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Parameters

Section titled “Parameters”
Name In Type Required Description
firm_id query string no Events of this firm.
icp_id query string no Events for this ICP, each scored (one score_signal billed per scored event).
since query string (date-time) no Only events observed at or after this time.
types query string no Comma-separated event types to include, for example filing,fund_raise.
min_p query number or null no With icp_id: only events whose relevant is at least this.
cursor query string no Opaque cursor from the next_cursor of the previous page. Omit it for the first page.
limit query integer no Page size, 1 to 200. Default 50.
x-verdict-version header string no API version to use, a date. Defaults to the version current when the key was created. The current version is 2026-11-01.

Response fields (200)

Section titled “Response fields (200)”
Field Type Required Description
data array of Event yes Events, newest first.
data[].id string no The event id.
data[].firm_id string no The firm the event happened to.
data[].occurred_at string (date-time) no When the event happened, per the source.
data[].observed_at string (date-time) no When Verdict ingested the event.
data[].source enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata” no The index source.
data[].source_url string (uri) no Link to the event at the source.
data[].confidence number no Confidence in the event’s normalization and firm keying.
data[].score EventScore no The event’s score for the requested ICP, or null when read without icp_id.
data[].score.decision_id string yes The score_signal decision that produced this score (billed once).
data[].score.icp_id string yes The ICP profile the event was scored against.
data[].score.relevant number yes Calibrated probability that the event matters for the ICP’s offer.
data[].score.act_now number yes Calibrated probability that now is the time to act.
data[].score.window_days integer or null yes Days left to act on the event, or null when there is no clear window.
data[].score.answer enum: “relevant”, “not_relevant” yes relevant applied to the threshold.
data[].score.reason_code enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data” yes Why, as a score_signal reason code.
data[].type enum: “filing” no Event type filing.
data[].attributes object no Attributes of a filing event.
data[].attributes.filing_type enum: “sec_8k”, “sec_form_d”, “sec_form_4”, “sec_s1”, “sec_13f”, “sec_adv” yes The filing sub-type.
data[].attributes.accession_number string no SEC accession number.
data[].attributes.items array of string no 8-K item numbers reported, for sec_8k.
data[].attributes.title string no Filing title or form description.
data[].attributes.form string no The form type exactly as the source lists it, for example 8-K/A or 13F-HR.
data[].attributes.file_number string no SEC file number, for example 333-299845.
next_cursor string or null yes Pass as cursor to fetch the next page. null when this is the last page.
has_more boolean yes Whether another page follows.

Errors

Section titled “Errors”

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status Meaning
400 Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (invalid_request).
401 Missing, malformed, revoked or expired API key, or a bad webhook signature (unauthorized).
402 Payment required: the balance cannot cover the call (insufficient_balance), or the call would exceed X-Max-Cost-USD (max_cost_exceeded). Nothing was spent.
403 The key lacks the scope this operation needs (forbidden_scope).
404 The resource does not exist in this organization (not_found).
429 Rate limited (rate_limited). Wait Retry-After seconds.
500 Unexpected server error (internal). Not billed; retry with the same Idempotency-Key.
503 Temporarily unavailable: the decision model failed, timed out or is rate limited, or decisions are switched off (decision_unavailable), or a vendor the call depends on is unavailable (vendor_unavailable, phase 2). Not billed. Wait Retry-After seconds and retry with the same Idempotency-Key.

Try it

Section titled “Try it”

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.