> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.tamtam.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a people search to the end in the background > Collect every person a search matches, up to 100,000, without paging it yourself. Takes the same filters as [Search for people](/api-reference/people-search/search-for-people), plus how many people to save and, optionally, a contacts list name to save them into. Returns at once with a job to poll. The job is the same one the app runs for "Add all to a list": - **Large searches are split.** A source serves at most 2,500 people for one search, so a larger one is first split into narrower searches that each fit (by job title, then country, company size and industry), and those run four at a time. A person matching two of them is saved once. When a slice cannot be split under the limit, the people beyond it are reported in `unreachable_count` rather than silently missing. - **Pages are paced.** Every job on a source shares one pace set by Tamtam, so running several at once queues them rather than getting them throttled; a page the source still refuses is retried with backoff from where it stopped. With `provider: "endor"`, whose searches have no 2,500 limit, the search is not split and runs whole. **Reading the results:** poll the job, and read the people from the results endpoint, which works while the job runs. With `list_name`, they are also saved into contacts lists of 10,000. Costs 1 credit per person fetched, as a search does. A job ends as `out_of_credits` when the balance runs out, and keeps what it saved. ## OpenAPI ````yaml /reference/openapi.yaml post /v2/people/search-jobs openapi: 3.1.0 info: title: Tamtam Public API version: 2.0.0 servers: - url: https://api.tamtam.ai/api security: [] paths: /v2/people/search-jobs: post: tags: - People Search summary: Run a people search to the end in the background description: >- Collect every person a search matches, up to 100,000, without paging it yourself. Takes the same filters as [Search for people](/api-reference/people-search/search-for-people), plus how many people to save and, optionally, a contacts list name to save them into. Returns at once with a job to poll. The job is the same one the app runs for "Add all to a list": - **Large searches are split.** A source serves at most 2,500 people for one search, so a larger one is first split into narrower searches that each fit (by job title, then country, company size and industry), and those run four at a time. A person matching two of them is saved once. When a slice cannot be split under the limit, the people beyond it are reported in `unreachable_count` rather than silently missing. - **Pages are paced.** Every job on a source shares one pace set by Tamtam, so running several at once queues them rather than getting them throttled; a page the source still refuses is retried with backoff from where it stopped. With `provider: "endor"`, whose searches have no 2,500 limit, the search is not split and runs whole. **Reading the results:** poll the job, and read the people from the results endpoint, which works while the job runs. With `list_name`, they are also saved into contacts lists of 10,000. Costs 1 credit per person fetched, as a search does. A job ends as `out_of_credits` when the balance runs out, and keeps what it saved. operationId: create-people-search-job requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePeopleSearchJobInputBody' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/PeopleSearchJobDto' description: Accepted default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - apikeyAuth: [] - bearerAuth: [] components: schemas: CreatePeopleSearchJobInputBody: additionalProperties: false properties: canonical_job_titles_excludes_ids: description: Canonical job title IDs to exclude items: type: string type: - array - 'null' canonical_job_titles_includes_ids: description: Canonical job title IDs to include items: type: string type: - array - 'null' company_headcounts: description: >- Company headcount band codes (single letter). A=self-employed, B=1-10, C=11-50, D=51-200, E=201-500, F=501-1000, G=1001-5000, H=5001-10000, I=10001+. examples: - - C items: type: string type: - array - 'null' company_hq_countries: description: Company HQ country codes examples: - - FR items: type: string type: - array - 'null' company_linkedin_ids: description: LinkedIn company IDs to filter by examples: - - '104924588' items: type: string type: - array - 'null' countries: description: Country codes to filter by examples: - - FR items: type: string type: - array - 'null' country_excludes: description: >- Country codes to exclude. Narrows a search rather than describing one, so it cannot be the only filter sent. examples: - - BE items: type: string type: - array - 'null' first_name: description: Filter by first name examples: - Elliot type: string industry_excludes_ids: description: >- Industry IDs to exclude. Resolve via [Search industries](/api-reference/industries/search-industries) and pass the returned id. examples: - - c4d7e6f3-2345-4bcd-aef0-123456789abc items: type: string type: - array - 'null' industry_includes_ids: description: >- Industry IDs to include. Resolve via [Search industries](/api-reference/industries/search-industries) and pass the returned id. examples: - - b3c6f5e2-1234-4abc-9def-0123456789ab items: type: string type: - array - 'null' job_titles_excludes: description: Job titles to exclude examples: - - Intern items: type: string type: - array - 'null' job_titles_includes: description: Job titles to include examples: - - Head of Sales items: type: string type: - array - 'null' keywords: description: >- Free-text search over the whole profile: headline, About, every role's title and description, skills, education. A boolean expression — uppercase AND / OR, double quotes around phrases, parentheses for grouping, implicit AND between bare words — passed through to LinkedIn as written. Honored or the search fails: when no configured provider supports profile keywords, the request returns 503 rather than a page that ignores the expression. examples: - '"supply chain" AND SAP' type: string last_name: description: Filter by last name examples: - Alderson type: string list_name: description: >- Also save the people into Tamtam contacts lists, 10,000 per list: a new list with this name, then '_2', '_3' and so on. The lists fill as the job runs. Omit to save no list; the people are readable from the results endpoint either way. examples: - HR leaders FR type: string max_results: description: >- Stop once this many people are saved. Omit to save every match, up to 100,000. examples: - 100000 format: int64 maximum: 100000 minimum: 1 type: integer persona_id: description: >- Search using one of your saved personas, which supplies the job titles, countries and seniority bands behind it. List them via [List personas](/api-reference/personas/list-personas). Any filter you also send explicitly overrides the persona's value for that field; combine it with company_linkedin_ids to search a persona within specific companies. Mutually exclusive with prompt. One persona per call — to search several, call once per persona. examples: - b3c6f5e2-1234-4abc-9def-0123456789ab type: string profile_languages: description: >- Languages the person's LinkedIn profile is written in (ISO 639-1: en, fr, de, es, it, nl, pt), ORed. The language of the profile, not of the person. Include only: a language cannot be excluded. Omitted, the persona's languages apply when a persona is given. examples: - - en items: type: string type: - array - 'null' prompt: description: >- Free-text search prompt (e.g. 'CTOs at fintech startups in France'). Mutually exclusive with filter fields. examples: - Head of Sales at AI startups in France type: string provider: description: >- Run the search on one specific people-search source, with no fallback to another. Omit to let Tamtam choose, which is the default and falls back when a source is unavailable. endor does not support keywords: a search carrying them is refused with a 400 rather than run without them. It also ignores years_of_experience. Read on the first page only. Later pages always stay on the source that served the first, since next_cursor belongs to it. enum: - endor - bespin examples: - endor type: string recently_changed_jobs: description: Only include people who recently changed jobs examples: - true type: boolean seniority_excludes: deprecated: true description: >- Deprecated and IGNORED. There is no exclude form: the filter keeps the bands you ask for plus everyone it cannot classify, which an exclude list cannot express. Use seniority_includes. items: type: string type: - array - 'null' seniority_includes: description: >- Seniority bands to keep, derived from each person's job title. Allowed values: 'Owner / Partner', 'CXO', 'Vice President', 'Director', 'Experienced Manager', 'Senior', 'Entry Level', 'In Training'. A person whose title carries no seniority signal is kept rather than dropped, so this narrows results without discarding the unlabelled. 'Entry Level Manager' is accepted and behaves as 'Experienced Manager'; 'Strategic' is accepted and has no effect. examples: - - Director - CXO items: type: string type: - array - 'null' use_persona_ai_extension: description: >- Whether this search widens the persona with Tamtam's AI extension of it: extra job titles inferred from the roles that actually convert for you, held outside the persona's own definition so they never appear in it. Omit to use whatever the persona is set to — the default, and what the app itself does. Send false to search only the job titles written on the persona; the extension is recomputed periodically, so this is the setting that makes a search reproducible. Send true to widen even when the persona has the extension switched off. Sending true has no effect on a persona for which no extension has been computed yet. Requires persona_id. examples: - false type: boolean years_of_experience: description: >- Refinement hint forwarded to the underlying provider. Allowed values: 'Less than 1 year', '1 to 2 years', '3 to 5 years', '6 to 10 years', 'More than 10'. Best-effort — not all providers honor this field, and matches that ignore it may still be returned. examples: - - 6 to 10 years items: type: string type: - array - 'null' type: object PeopleSearchJobDto: additionalProperties: false properties: contacts_list_ids: description: >- The contacts lists the job has filled so far, in order, 10,000 people each. Empty when no list was asked for. items: type: string type: - array - 'null' created_at: description: When the job was created format: date-time type: string error: description: >- Why a failed job stopped: planning_failed, search_failed or start_failed examples: - planning_failed type: string finished_at: description: When the job ended, whatever the reason format: date-time type: string job_id: description: The job's ID, to poll it, read its results or stop it examples: - b3c6f5e2-1234-4abc-9def-0123456789ab type: string max_results: description: The cap the job stops at. 0 while planning. examples: - 100000 format: int64 type: integer plan: description: >- The searches the job was split into, in the order they run. Empty while planning. items: $ref: '#/components/schemas/PeopleSearchJobPlannedSearchDto' type: - array - 'null' provider: description: The source the job was pinned to, when one was asked for examples: - endor type: string saved_count: description: How many distinct people the job has saved so far examples: - 12500 format: int64 type: integer searches: description: >- How many searches the job was split into. 1 for a search the source serves whole. examples: - 24 format: int64 type: integer searches_failed: description: >- How many of those failed after repeated retries. What they saved before failing is kept. examples: - 0 format: int64 type: integer searches_finished: description: How many of those have run to their end examples: - 10 format: int64 type: integer status: description: >- planning while the search is split into searches the source can serve whole. planned once the plan is ready: a job started with the plan endpoint waits there until you run it, one started to run goes straight on. running while pages are collected. completed when every search ran to its end or max_results was reached. stopped when you stopped it. out_of_credits when the account ran out of credits. failed when it could not go on, see error. Whatever ends a job, what it saved is kept. enum: - planning - planned - running - completed - stopped - out_of_credits - failed examples: - running type: string unreachable_count: description: >- People the search matches that no split could bring within reach of the source, and that the job will therefore not collect. See the operation description. examples: - 0 format: int64 type: integer required: - job_id - status - max_results - saved_count - unreachable_count - searches - searches_finished - searches_failed - plan - contacts_list_ids - created_at type: object ErrorModel: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object PeopleSearchJobPlannedSearchDto: additionalProperties: false properties: label: description: >- What this search is: the original search narrowed to one slice. Empty for a search that was not split. examples: - HR Manager · FR · 501-1000 type: string result_count: description: >- How many people the source counts for this search. At most 2,500 are collected from it: a count above that is a slice no split could narrow, whose surplus is in unreachable_count. Absent when the source was not counted, for a search pinned to endor. examples: - 1840 format: int64 type: integer required: - label type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object securitySchemes: apikeyAuth: description: Account API key passed in the Authorization header in: header name: Authorization type: apiKey bearerAuth: description: Bearer JWT obtained via the OAuth 2.1 authorization flow scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.