Skip to content

Run Ai Enrichment

POST
/enrichment/ai/enrich

Run a saved AI enrichment config (web-research / content-gen) on records.

Delegates to AIEnrichmentHandler (the same handler the UI uses). Unlike the waterfall endpoint - which queues an async job - this call runs synchronously: handler.run() blocks until every record has been processed (typical: 30-120 s for a handful of contacts on the web-research usecase). The response therefore returns status="completed" with the final counters inline, not a queued job_id to poll.

The job_id is still returned for audit / cross-reference - polling it via GET /jobs/{job_id} works thanks to the DB fallback on that endpoint, but most callers will get everything they need from this response directly.

Credits are charged up-front at the web-research baseline (CREDITS_AI_ENRICH_ESTIMATE). The handler does not charge additionally, so this is the only credit deduction per call.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Run a saved AI enrichment config on specific records.

The prompt, model, outputs, and column mapping live on the config referenced by group_id. We accept record_ids so callers can target exactly the contacts they want enriched.

object
group_id
required

Group_id of a saved AI enrichment config (starts with ‘ai_enrich’)

string
list_id
required

List ID the records belong to

integer
max_records
Any of:
integer
record_ids
required

Contact IDs to enrich

Array<integer>
skip_existing_values
Any of:
boolean

Responses

200

Successful Response

object
data
required
object
completed
Any of:
integer
failed_enrichments
Any of:
integer
job_id
required
string
provider_errors
Any of:
Array<object>
object
key
additional properties
any
results
Any of:
Array<object>
object
key
additional properties
any
status
required
string
successful_enrichments
Any of:
integer
total
Any of:
integer
total_credits_used
Any of:
integer
warnings
Any of:
Array<string>
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string