API Reference › Property Search
TraceAI Assist
POST /v1/api/property-search/ai-assist/
Cost: 1 credit per search returned. Follow-up questions and failed calls cost nothing.
Rate limit: No fixed limit.
Mode: Sync
Translate a plain-English description of your ideal customer into a structured strategy + geography + filter_overrides spec you can pipe straight into /preview/ or /execute/. This is the fastest way to build a lead list from code, one call to describe, one call to run.
Billing: 1 credit when TraceAI returns a search. A follow-up question (needs_clarification: true) and a failed call (503) cost nothing.
When the AI isn't sure: if your prompt is ambiguous ('Springfield', 'LA'), the response will include needs_clarification: true, a clarifying_question, and a conversation_id. To reply, pass the same conversation_id along with the user's answer in a new call, the AI loads the full conversation history and picks up where it left off.
Conceptual questions like "what is a tired landlord" return needs_clarification: true with the explanation in rationale.summary, don't run a search on those, ask the user where they want to target first.
Neighborhood-level targeting: say "plumbing leads in South Side Chicago" or "downtown Nashville probate" and TraceAI will pick the ZIP codes that cover the area from its general knowledge. No need to hand-roll ZIP lists.
Related endpoints: List Saved Templates · Create a Saved Template · Get a Saved Template
Fields
prompt (required): Plain-English description of the target audience. 5-2000 characters. Example: 'plumbing leads in South Side Chicago' or 'absentee owners with 50%+ equity in Tampa built before 1990'.
conversation_id: UUID from a previous response. Pass this to continue a clarification thread, the AI loads all prior turns automatically.
Responses
200: Successful: filters applied, ready to pipe into /preview/ or /execute/
400: Missing / too-long prompt or bad conversation_id: Empty prompt
402: Insufficient credits
500: Unexpected error
502: AI provider error (not charged)
503: AI assist not configured on this server