> ## 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. # Read people's experiences > Return the LinkedIn experiences of up to 20 profiles, current position first, at the refresh price rather than the discovery price. For a profile Tamtam already holds this is free: experiences refreshed within the last 30 days are answered from what Tamtam holds with no provider call (`source: cached`), older ones are re-read from LinkedIn (`source: refreshed`). Pass `force: true` to re-read regardless. For a profile Tamtam does not hold, the row falls back to a full extract, which creates a contact and costs 1 credit exactly as `POST /v2/people/extract` (`source: extracted`). Pass `refresh_only: true` to refuse that fallback; the row then carries `error: profile_unknown` and nothing is spent. Each row answers on its own: one profile gone from LinkedIn or one failed provider call is an `error` on that row while the rest are answered. The one whole-batch refusal is **402**, checked before anything runs, when the fallback extracts the batch would need cannot be paid for. Free for a profile Tamtam holds; 1 credit per profile it extracts. ## OpenAPI ````yaml /reference/openapi.yaml post /v2/people/experiences openapi: 3.1.0 info: title: Tamtam Public API version: 2.0.0 servers: - url: https://api.tamtam.ai/api security: [] paths: /v2/people/experiences: post: tags: - People Extract summary: Read people's experiences description: >- Return the LinkedIn experiences of up to 20 profiles, current position first, at the refresh price rather than the discovery price. For a profile Tamtam already holds this is free: experiences refreshed within the last 30 days are answered from what Tamtam holds with no provider call (`source: cached`), older ones are re-read from LinkedIn (`source: refreshed`). Pass `force: true` to re-read regardless. For a profile Tamtam does not hold, the row falls back to a full extract, which creates a contact and costs 1 credit exactly as `POST /v2/people/extract` (`source: extracted`). Pass `refresh_only: true` to refuse that fallback; the row then carries `error: profile_unknown` and nothing is spent. Each row answers on its own: one profile gone from LinkedIn or one failed provider call is an `error` on that row while the rest are answered. The one whole-batch refusal is **402**, checked before anything runs, when the fallback extracts the batch would need cannot be paid for. Free for a profile Tamtam holds; 1 credit per profile it extracts. operationId: get-people-experiences requestBody: content: application/json: schema: $ref: '#/components/schemas/GetPeopleExperiencesInputBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetPeopleExperiencesOutputBody' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - apikeyAuth: [] - bearerAuth: [] components: schemas: GetPeopleExperiencesInputBody: additionalProperties: false properties: force: description: >- Re-read the experiences from LinkedIn even when Tamtam refreshed them within the last 30 days. Default false: a profile refreshed within 30 days is answered from what Tamtam holds, at no cost and no provider call. type: boolean refresh_only: description: >- Never fall back to a full profile extract for a profile Tamtam does not hold. Default false: an unknown profile is extracted, which creates a contact and costs 1 credit, exactly as POST /v2/people/extract. Set true for a run that must not spend discovery credits; unknown profiles then come back with error profile_unknown. type: boolean requests: description: Profiles to read, at most 20 per call. items: $ref: '#/components/schemas/PeopleExperiencesRequestDto' maxItems: 20 minItems: 1 type: - array - 'null' required: - requests type: object GetPeopleExperiencesOutputBody: additionalProperties: false properties: results: description: One entry per request row, in the same order. items: $ref: '#/components/schemas/PeopleExperiencesItemDto' type: - array - 'null' required: - results 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 PeopleExperiencesRequestDto: additionalProperties: false properties: custom: additionalProperties: type: string description: Custom key-value pairs echoed back on the result, e.g. your row id. type: object linkedin_url: description: LinkedIn profile URL. examples: - https://www.linkedin.com/in/jean-dupont minLength: 1 type: string required: - linkedin_url type: object PeopleExperiencesItemDto: additionalProperties: false properties: current_experience: $ref: '#/components/schemas/ExtractPersonExperienceDto' description: The first experience with no end date, when there is one. custom: additionalProperties: type: string description: The custom map from the request row, echoed back. type: object error: description: >- Why the row has no experiences: invalid_linkedin_url; profile_unknown (Tamtam does not hold the profile and refresh_only was set); not_found_on_linkedin (LinkedIn reports the profile gone); out_of_credits (the fallback extract could not be paid for); extraction_failed (the provider call failed; retry later). Absent when answered. examples: - profile_unknown type: string experiences: description: >- The profile's experiences, most recent first. Empty when the row errored. items: $ref: '#/components/schemas/ExtractPersonExperienceDto' type: - array - 'null' linkedin_url: description: The URL from the request row. type: string source: description: >- Where the experiences came from. cached: Tamtam held them, refreshed within 30 days, no provider call and no charge. refreshed: Tamtam held the profile and re-read its experiences from LinkedIn, no charge. extracted: Tamtam did not hold the profile and ran a full extract, which created a contact and cost 1 credit. Absent when the row errored. enum: - cached - refreshed - extracted examples: - cached type: string required: - linkedin_url - experiences 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 ExtractPersonExperienceDto: additionalProperties: false properties: company_linkedin_id: description: Company LinkedIn numeric ID type: string company_name: description: Company name type: string company_slug: description: Company LinkedIn slug type: string country_code: description: Country code (2-letter ISO) type: string description: description: Experience description type: string end_date: description: End date (YYYY-MM), null if current examples: - 2024-06 type: string location: description: Location (free text) type: string start_date: description: Start date (YYYY-MM) examples: - 2022-01 type: string title: description: Job title type: string required: - title 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 ````