---
title: "Update an AI Lead Finder Agent"
method: PATCH
path: "/api/v2/ai-agents/lead-finder/{id}"
tags: ["AILeadFinderAgent"]
---

# Update an AI Lead Finder Agent

`PATCH /api/v2/ai-agents/lead-finder/{id}`

## Request

- Base URL: `https://api.instantly.ai`
- URL: `https://api.instantly.ai/api/v2/ai-agents/lead-finder/{id}`
- Auth: HTTP bearer

Update an AI Lead Finder Agent's settings. `on_exhaustion: fallback` requires fallback filters, either in this request or already stored.


Requires one of the following scopes: `ai_agents:update`, `ai_agents:all`, `all:update`, `all:all`

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `name` string: Name of the agent
  - `campaign_id` string, uuid: Reassign the agent to another campaign. A campaign can have at most one active agent.
  - `min_active_leads` number: Threshold below which the agent tops up the campaign
  - `on_exhaustion` 'pause' | 'fallback' | 'broaden': What the agent does when the search runs out of new leads
  - `show_one_lead_per_company` boolean: Deliver at most one lead per company in each top-up
  - `ai_enrichment` object, nullable: AI enrichment columns filled on every top-up, keyed by output column name. Leads are held back until they are filled.
  - `ai_enrichment_workflow` string: Workflow template the enrichment chain was loaded from — a built-in key or `custom:<id>`. Display-only.

## Response `200`

The updated AI Lead Finder Agent

- AILeadFinderAgent: An AI Lead Finder Agent
  - `id` string, uuid, required: Unique identifier for the AI agent
  - `organization_id` string, uuid, required: Organization ID
  - `name` string, required: Name of the AI Agent
  - `payload` object: Lead Finder Agent payload
    - `campaign_id` string, uuid, required: Campaign this agent keeps topped up
    - `campaign_name` string: Denormalized campaign name
    - `search_filters` object: Primary audience search filters
    - `min_active_leads` number: Threshold below which the agent tops up the campaign
    - `on_exhaustion` 'pause' | 'fallback' | 'broaden': What the agent does when the search runs out of new leads
    - `fallback_search_filters` object, nullable: Optional fallback audience used when the primary search is exhausted
    - `ai_enrichment` object, nullable: AI enrichment columns the agent fills on every top-up, keyed by output column name. Returned in the stored executor shape; the write shape is documented on the create and update endpoints.
    - `ai_enrichment_workflow` string, nullable: Workflow template the enrichment chain was loaded from — a built-in key or `custom:<id>`.
  - `type` 6, nullable: Type of the AI Agent
  - `timestamp_created` string, required: Timestamp when the AI agent was created
  - `timestamp_updated` string, required: Timestamp when the AI agent was updated
  - `status` -1 | 0 | 1, required: Status of the AI Agent
  - `is_auto_created` boolean, nullable: Whether the AI agent was auto-created
  - `created_by` string, uuid, nullable: User ID who created the AI agent
  - `description` string, nullable: Description of the AI agent

## Other responses

- `400`: The request is invalid (e.g. missing required fields, invalid field values, or an invalid state for the operation)
- `401`: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402`: This request cannot be fulfilled because the workspace does not have an active paid plan
- `403`: This request is forbidden (the API key scope or workspace plan does not allow this action)
- `404`: The requested resource was not found
- `409`: The target campaign already has another active AI Lead Finder Agent
- `429`: You have exceeded the rate limit. Please check the rate limit docs for more information.

## Changes

- **2026-11-03** `c781051105a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/instantly/apis/api-explorer/changes/api/v2/ai-agents/lead-finder/:id/patch.md)

---

[API](https://skmtc.dev/instantly/apis/api-explorer.md) - [All operations](https://skmtc.dev/instantly/apis/api-explorer/llms.txt) - [OpenAPI document](https://skmtc.dev/instantly/apis/api-explorer/revisions/406ab2c4f714?raw)