Agentic Search

Introduction

The Agentic Search endpoint takes one sentence, such as VP Sales at software companies with 51 to 200 employees in Paris, reads it into People search filters, runs that search and returns the matching full profiles. You do not build the filters yourself: the response tells you which ones were applied, in data.interpretation.

Every result is a complete profile, the same shape People search returns, with the same cursor pagination. Results are drawn from our cache-based search index. This endpoint never triggers a live fetch.

Use it when the request comes from a person typing what they want, or when you prefer not to map criteria to filter names. To control every filter yourself, use People search.

Authorization

Request body

Prompt length: the 1000 token limit is about 4000 characters of English text. It is counted conservatively: four plain ASCII characters count as one token, and every other character (an accented letter, a non-Latin script) counts as one token on its own. A longer prompt returns HTTP 422 with error.code INVALID_PROMPT and costs 0 credits.

No filters: the filters come from the prompt, so the request takes no search filter. Any other field, such as location or currentSeniority, returns HTTP 422 with error.code PROMPT_FILTERS_NOT_SUPPORTED and the offending fields in error.details.fields, and costs 0 credits. A filter is refused rather than ignored, because an ignored filter would return results you did not ask for. Describe it in the prompt instead, or send explicit filters to People search.

What a prompt can express

A prompt is read into these People search filters:

Job titles and company names are matched as written, with the same token-based matching as People search, so write a title the way it appears on profiles. A seniority word such as VP or Director is matched inside the job title: the position taxonomy filters (currentFunction, currentSubFunction, currentSeniority and experience) are not read from a prompt yet. To filter on them, use People search.

Anything the prompt asks for that no filter covers, such as schools or contract types, is left out of the search and reported in data.interpretation.warnings, so you can see what the results do not take into account.

Pagination and credits

Agentic Search uses cursor pagination, like People search. Each response returns up to perPage profiles (1 to 100, default 25) and a metadata.nextCursor value. To get the following page, send the same prompt again with that value as cursor; nextCursor is null on the last page. The cursor is opaque: send it back unchanged, without parsing or altering it. There is no page parameter, and perPage may change from one page to the next.

The cursor does not expire, and a long pause between two pages is fine: the next page picks up where the previous one stopped. If profiles were refreshed in the meantime, one of them can occasionally repeat or be skipped at the page boundary. What a cursor needs is the same filters. A prompt keeps the filters it was first read into for 24 hours in your workspace, so resending it unchanged, from any of your API keys, always runs the same search. Spaces and line breaks do not count as a change. If you edit the prompt, or come back after 24 hours, the prompt is read again, and a cursor sent with filters other than the ones that produced it returns HTTP 400 and costs 0 credits: start again from the first page, without cursor.

perPage above 100 returns HTTP 422 with error.code PAGINATION_LIMIT_EXCEEDED, and a perPage that is not a whole number returns HTTP 422 with error.code INVALID_PAGINATION.

Agentic Search costs 1 credit per page for the search itself, plus 1 credit per profile delivered. The search credit is charged on every page, including when no profile matches. Compliance-blocked profiles are removed before the response and are not billed. A page that returns 25 profiles costs 26 credits, and a page that returns no profile costs 1 credit. A request refused before the search runs, for any of the reasons listed under Errors, costs 0 credits. Lower perPage to control how many credits a single request can spend.

Tip: data.interpretation.filters is a valid People search body. Send it to the free People search count endpoint to know how many people match in total, or to People search to adjust a filter by hand.

Errors

Every error below answers before the search runs, and costs 0 credits. When the prompt was read, error.details.interpretation carries the filters and warnings it produced, so you can see why it could not run.

Response structure

Note: This endpoint uses a nested envelope. The top-level V2 data field wraps an inner search payload that contains the actual results array (data.data), the pagination info (data.metadata) and the filters read from the prompt (data.interpretation). See the example response for the exact shape.

Code examples

curl -X POST https://api.reversecontact.com/v2/search/people/prompt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "VP Sales at software companies with 51 to 200 employees in Paris who speak German and studied at HEC",
    "perPage": 25
  }'

const prompt = "VP Sales at software companies with 51 to 200 employees in Paris who speak German and studied at HEC";

const promptPage = async (cursor) => {
  const response = await fetch("https://api.reversecontact.com/v2/search/people/prompt", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    // The same prompt travels with every page, the cursor only from the second one.
    body: JSON.stringify({ prompt, perPage: 25, cursor })
  });

  return response.json();
};

const firstPage = await promptPage();
const { filters, warnings } = firstPage.data.interpretation;
console.log("Filters applied:", filters, "Not applied:", warnings);

const profiles = firstPage.data.data;
const { nextCursor } = firstPage.data.metadata;
if (nextCursor) {
  const secondPage = await promptPage(nextCursor);
  profiles.push(...secondPage.data.data);
}

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/search/people/prompt",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "VP Sales at software companies with 51 to 200 employees in Paris who speak German and studied at HEC",
        "perPage": 25
    }
)

payload = response.json()
interpretation = payload["data"]["interpretation"]
profiles = payload["data"]["data"]
print(f"Filters applied: {interpretation['filters']}")
print(f"Got {len(profiles)} profiles, next cursor: {payload['data']['metadata']['nextCursor']}")

Example response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "prs_01h2x3y4z5a6b7c8d9e0f1g2h3",
        "publicId": "claire-martin",
        "memberId": "ACoAAB67890",
        "linkedinUrl": "https://www.social.com/in/claire-martin",
        "firstName": "Claire",
        "lastName": "Martin",
        "headline": "VP Sales at Northwind | B2B SaaS",
        "summary": "Sales leader building revenue teams for European software companies.",
        "pronoun": null,
        "isOpenToWork": false,
        "hasPremium": true,
        "hasVerificationBadge": false,
        "isInRemembrance": false,
        "photoUrl": "https://media.licdn.com/dms/image/v2/D4E03AQ.../profile-photo.jpg",
        "backgroundUrl": null,
        "creationDate": "2011-05-02T00:00:00.000Z",
        "followersCount": 3120,
        "connectionsCount": 500,
        "location": {
          "city": "Paris",
          "state": "Île-de-France",
          "country": "France",
          "countryCode": "FR",
          "rawLocation": "Paris, Île-de-France, France"
        },
        "currentPosition": {
          "title": "VP Sales",
          "description": "Leading a sales team of 18 across France and the DACH region.",
          "contractType": "Full-time",
          "companyName": "Northwind",
          "companyLinkedinId": "23456789",
          "companyUrl": "https://www.social.com/company/northwind",
          "companyLocation": "Paris, France",
          "companyLogoUrl": "https://media.licdn.com/dms/image/v2/C4E0BAQ.../logo.jpg",
          "startEndDate": {
            "start": "2022-03-01T00:00:00.000Z",
            "end": null
          }
        },
        "experience": [
          {
            "title": "VP Sales",
            "description": "Leading a sales team of 18 across France and the DACH region.",
            "contractType": "Full-time",
            "companyName": "Northwind",
            "companyLinkedinId": "23456789",
            "companyUrl": "https://www.social.com/company/northwind",
            "companyLocation": "Paris, France",
            "companyLogoUrl": "https://media.licdn.com/dms/image/v2/C4E0BAQ.../logo.jpg",
            "startEndDate": {
              "start": "2022-03-01T00:00:00.000Z",
              "end": null
            }
          }
        ],
        "education": [],
        "skills": ["SaaS Sales", "Team Leadership", "Negotiation"],
        "languages": [
          { "language": "French", "proficiency": "Native or bilingual" },
          { "language": "German", "proficiency": "Professional working proficiency" }
        ],
        "certifications": [],
        "recommendations": [],
        "testScores": []
      }
    ],
    "metadata": {
      "perPage": 25,
      "count": 1,
      "nextCursor": "cur_01j9x9s6p4b0d8f6h2c4e0g8"
    },
    "interpretation": {
      "filters": {
        "currentPositionTitle": "VP Sales",
        "currentCompanyIndustry": "Software Development",
        "currentCompanyEmployeeCountRange": { "min": 51, "max": 200 },
        "location": { "countryCode": "FR", "city": "Paris" },
        "languages": "German"
      },
      "warnings": ["Not available as filters yet: school."]
    }
  },
  "error": null,
  "metadata": {
    "requestId": "req_p1r2o3m4p5t6",
    "executionTimeMs": 5210
  },
  "quotas": {
    "creditsConsumed": 2,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4523,
        "left": 5477
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2026-09-29T14:16:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2026-09-29T14:16:00.000Z"
      }
    }
  }
}