Skip to content
POST/api/v2/ioc/verdict/bulk

Bulk IOC Verdict

Query threat intelligence for up to 10,000 indicators in a single request. **Requires API key with `verdict_bulk` permission.** **Payload format (v2 — shared params + indicators list):** Shared parameters (`context`, `source`, `signal_details`, `evidence_details`, `scoring_version`, `query_type`, `project_id`, `project_name`) are declared **once** at the top level. The `indicators` array contains only `{type, value}` objects. This dramatically reduces payload size for large batches (typical 10k payload: ~3.5 MB → ~0.36 MB, ~90% smaller). **Bulk-specific behavior:** - `signal_details` default is `none` (set `top` or `all` to include signals). - `evidence_details` is always `none` in bulk; the field is ignored if sent. - Per-indicator overrides are **not** supported — the entire batch shares one parameter set. **Response shape:** Top-level `meta` (engine_version, data_timestamp, bulk_request_id, signal_details, evidence_details, took_ms, record_count) is hoisted out of per-result meta. Per-result objects contain no `meta` field; flat `warnings`/`errors` are present only when populated. **Pipeline:** Indicators are split into chunks and queried against the cache in parallel; scoring runs concurrently per chunk. SaveHistory is dispatched on a bounded worker pool off the request hot path. **Quota tracking:** Each indicator generates one `cx_enrich_log` record and one usage-counter increment, so quota accounting is identical to single-call usage.

EnrichmentView OpenAPI spec ↗

Request body

  • indicatorsobject[]required
    List of indicators to enrich (max 10000)
    • typeenumipdomainip_blockfile_hash_sha256asn
    • valuestringrequired
    • action_takenenumblockallow
      Optional, log-only. See action_taken on the single EnrichRequest indicator. Does not affect the verdict or the cache key.
    • action_sourcestring
      Optional, log-only. Free text (no fixed list); trimmed and lowercased before logging, normalized value max 64 characters (otherwise 400 INVALID_ACTION_SOURCE). See action_source on the single EnrichRequest indicator.
  • contextobject
    • flagsany
      Optional context flags
  • sourceobject
    Caller identification for audit logging (shared across all indicators in this batch)
    • channelstring
    • productstring
    • integration_idstring
    • event_typestring
    • severity_hintstring
  • signal_detailsenumnonetopall
    Bulk default is `none`. Applied to all indicators.
  • evidence_detailsenumnonesummaryfull
    Always `none` in bulk; field is ignored if sent.
  • scoring_versionstring
  • query_typestring
  • project_idstring
  • project_namestring

Example

json
{
  "indicators": [
    {
      "type": "domain",
      "value": "example.com"
    },
    {
      "type": "domain",
      "value": "example.org"
    }
  ]
}

Responses

Bulk Replay results

  • metaEnrichBulkMeta
    • engine_versionstring
    • data_timestampstring
    • bulk_request_idstring
      Stamped on every cx_enrich_log record produced by this bulk call.
    • signal_detailsstring
    • evidence_detailsstring
    • took_msinteger
      Total processing time in milliseconds
    • record_countinteger
      Number of result entries (matches request indicators length)
    • warningsstring[]
    • errorsstring[]
  • resultsEnrichBulkResultItem[]
    • indicatorobject
    • riskobject
    • signalsThreatSignal[]
    • signal_countinteger
    • scoresobject
    • threat_contextobject
    • recommended_actionsobject[]
    • warningsstring[]
      Present only when populated (e.g. validation warnings for this indicator).
    • errorsstring[]
      Present only when populated (e.g. invalid indicator value).

Code samples

bash
curl -X POST 'https://api.verdictiq.io/api/v2/ioc/verdict/bulk' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_<your-api-key>' \
  -d '{
  "indicators": [
    {
      "type": "domain",
      "value": "example.com"
    },
    {
      "type": "domain",
      "value": "example.org"
    }
  ]
}'