| name | audience |
| description | Create and manage Fiber AI audiences for bulk operations — search, enrich, and export lists of companies or contacts at scale. Use when the user wants to build a prospecting list or do bulk data operations. |
| user-invocable | true |
| argument-hint | <describe the audience you want to build> |
Fiber AI Audience Workflow
Audiences are the core workflow for bulk operations in Fiber AI. They allow searching, enriching, and exporting lists at scale.
For the complete, up-to-date workflow guide, read the MCP resource llms://fiber.ai/docs/audience-workflow via the Core MCP.
When to Use
- User wants to build a prospecting list
- User wants to bulk enrich contacts (more than 5 people)
- User wants to export data to CSV or download a list
- User says "create audience", "build list", "bulk enrich", "export", "prospecting list"
Do Not Use When
- User wants to search without saving results — use
/fiber:search instead
- User wants to enrich a single contact — use
/fiber:enrich instead
- User wants to write code for audience management — use
/fiber:sdk-ts or /fiber:sdk-py instead
The Audience Lifecycle
Each step must be completed in order. Do not skip steps. Build and enrichment are async — you must poll for completion.
Create → Set Search Params → Build → Poll Build Status → Estimate Cost → Enrich → Poll Enrichment Status → Export
How to Execute
All audience operations must go through the Core MCP using call_operation. They are not available as V2 direct tools.
Before calling any operation, use get_endpoint_details_full("operationId") to get the exact parameter schema. Parameters change over time — do not guess field names.
Step 1: Create Audience
- operationId:
createAudience
- Method:
POST /v1/audiences/create
apiKey goes in the request body- Save the returned audience ID for all subsequent steps
- Confirm creation with the user
Step 2: Set Search Parameters
- operationId:
updateAudienceSearchParams
- Method:
PATCH /v1/audiences/{audienceId}/search-params
apiKey goes in the request body- The body contains
companySearchParams and/or prospectSearchParams — these are separate filter objects with different schemas
- Call
get_endpoint_details_full("updateAudienceSearchParams") to see available filter fields
- Show the user what filters were applied and confirm before proceeding
- Can only be set while audience status is
DRAFT
Step 3: Build the Audience
- operationId:
buildAudience
- Method:
POST /v1/audiences/{audienceId}/build
- This step charges credits — always confirm with the user first
- Credits are charged per company found and per profile found
- Only after explicit confirmation: call the operation
- Status transitions:
DRAFT → BUILDING → NORMAL (or FAILED)
Step 4: Poll Build Status
- Build is async — you must poll until complete
- Call
call_operation("getAudience", {"query": {"apiKey": "..."}, "path": {"audienceId": "..."}}) or equivalent to check audience status
- Wait until status becomes
NORMAL before proceeding
- Poll every 10-30 seconds
- Report the number of entities found once build completes
Step 5: Estimate Enrichment Cost
- operationId:
estimateEnrichmentCost
- Method:
POST /v1/audiences/{audienceId}/enrichment/estimate
- Call
get_endpoint_details_full("estimateEnrichmentCost") for parameters including enrichment type options and limits
- Present the estimate clearly: number of contacts, cost breakdown, total credits needed
- Always get user confirmation before proceeding to enrichment
- This step is free (no credits charged)
Step 6: Enrich
- operationId:
triggerEnrichment
- Method:
POST /v1/audiences/{audienceId}/enrich
- Only after the user confirms the cost estimate
- Call
get_endpoint_details_full("triggerEnrichment") for exact parameters
- Enrichment types include work emails, personal emails, phone numbers, live profile enrichment, and more
Step 7: Poll Enrichment Status
- Enrichment is async — you must poll until complete
- operationId:
getEnrichmentStatus
- Method:
GET /v1/audiences/{audienceId}/enrichment/status
apiKey goes in the query string (not body) for GET requests- Poll every 30 seconds until enrichment is complete
- Report progress percentage to the user
Step 8: Export
Two separate export endpoints exist:
- operationId:
exportCompanies — POST /v1/audiences/{audienceId}/export/companies
- operationId:
exportProspects — POST /v1/audiences/{audienceId}/export/prospects
- Provide the download link to the user
- This step is free (no credits charged)
Important Rules
- NEVER skip the cost estimate step — always show costs and get confirmation before any credit-charging operation
- NEVER proceed to build or enrich without explicit user confirmation
- Always poll for completion after build and enrichment — they are async operations
- Show the audience summary at each step: name, filter count, entity count, status
- If the user seems unsure about costs, suggest checking their credit balance first via
getOrgCredits
- Keep the user informed of which step they are on in the lifecycle
Authentication
- For POST/PATCH endpoints:
apiKey is in the request body
- For GET endpoints:
apiKey is in the query string
- Check https://api.fiber.ai/docs/ for exact auth format per endpoint
For AI agents: machine-readable docs
Error Handling
- Audience creation fails: check API key and permissions via
/fiber:setup
- Build finds 0 results: suggest broadening search criteria (fewer filters, wider location range)
- Enrichment too expensive: suggest reducing audience size, narrowing filters, or selecting fewer enrichment types
- Export fails: verify the audience has been enriched and enrichment status is complete before attempting export
- Build status FAILED: check search parameters and retry, or create a new audience
