> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theswarm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Profile

> Retrieve detailed information about specific profiles by their unique identifiers.

The Fetch Profile endpoint retrieves specific profiles based on their unique identifiers (profile IDs or LinkedIn usernames).

The `fields` array accepts the following values:

* **tags** — Tags assigned to the profile.
* **lists** — Lists the profile is assigned to.
* **profile\_info** — Detailed profile data (work experience, education, etc.).

For request examples, see [Fetch endpoint examples](/docs/examples/fetch-endpoint).

For the full response schema, see [Models > Profile](/docs/enrichment-data/profile).

## Limits

Each identifier array (`ids`, `linkedin_usernames`, `linkedin_ids`, `linkedin_entity_ids`) accepts up to **1,000 values per request**. Combine arrays freely up to the per-array cap.

## Responses

In addition to the standard error responses, this endpoint may return:

* **`402 Payment Required`** — your team's API credit allowance has been exceeded. Top up or upgrade your plan to continue. See [Credits & Usage](/docs/api-reference/credits-usage).

## Partner teams

Partners can execute a request in the context of a child team by passing the child team's ID in the `x-authenticate-team` header:

```http theme={null}
x-authenticate-team: <child_team_id>
```

* **With the header** — the fetch runs in the context of the child team (e.g. list/tag membership reflects the child team).
* **Without the header** — the fetch runs in the context of the team that owns the API key (default).

The `child_team_id` is returned when you [create a child team](/docs/endpoints/v3/create-team).

```bash Example request theme={null}
curl -X POST https://bee.theswarm.com/v3/profiles/fetch \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-authenticate-team: child-team-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_usernames": ["john-doe"],
    "fields": ["profile_info", "tags", "lists"]
  }'
```

<Note>
  **Migrating from v2?** v3 uses snake\_case for all field names. The v2 equivalents were `linkedinNames`, `linkedinIds`, `linkedinEntityIds`, and `notFound`. See the [Migrating to v3](/docs/getting-started/migrating-to-v3) guide.
</Note>


## OpenAPI

````yaml openapi.json POST /v3/profiles/fetch
openapi: 3.1.0
info:
  title: Swarm API
  version: 1.0.0
  contact:
    name: The Swarm
    url: https://theswarm.com
    email: hello@theswarm.com
servers:
  - url: https://bee.theswarm.com
security:
  - ApiKeyAuth: []
tags:
  - name: profiles
    description: Operations related to profiles
  - name: companies
    description: Operations related to companies
  - name: teams
    description: Operations for managing teams and connectors
  - name: social
    description: Operations related to social media posts and interactions
  - name: mcp
    description: Model Context Protocol endpoint for AI assistant integrations
  - name: credits
    description: Operations related to credit usage
  - name: network-mapper
    description: Operations for mapping connections and relationships across your network
paths:
  /v3/profiles/fetch:
    post:
      tags:
        - profiles
      summary: Fetch profiles with corresponding data
      description: Fetch profiles with corresponding data (e.g. lists, tags)
      operationId: fetchProfilesV3
      parameters:
        - $ref: '#/components/parameters/AuthenticateTeamHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  maxItems: 1000
                  description: The Swarm profile IDs
                linkedin_names:
                  type: array
                  items:
                    type: string
                  maxItems: 1000
                  description: LinkedIn profile URL slugs
                linkedin_ids:
                  type: array
                  items:
                    type: integer
                  maxItems: 1000
                  description: LinkedIn numeric profile IDs
                linkedin_entity_ids:
                  type: array
                  items:
                    type: string
                  maxItems: 1000
                  description: LinkedIn alphanumeric entity IDs
                fields:
                  type: array
                  items:
                    type: string
                    enum:
                      - profile_info
                      - tags
                      - lists
                  default:
                    - profile_info
              anyOf:
                - required:
                    - ids
                - required:
                    - linkedin_names
                - required:
                    - linkedin_ids
                - required:
                    - linkedin_entity_ids
      responses:
        '200':
          description: A list of profiles with corresponding data
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    description: List of profiles with corresponding data
                    type: array
                    items:
                      $ref: '#/components/schemas/ProfileV3'
                  not_found:
                    description: >-
                      Identifiers (ids / linkedin_names / linkedin_ids /
                      linkedin_entity_ids) not found
                    type: array
                    items:
                      type: string
                required:
                  - results
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    AuthenticateTeamHeader:
      name: x-authenticate-team
      in: header
      required: false
      description: >-
        Partner accounts only. When present, the request is executed in the
        context of the specified child team (use the `team_id` returned by
        [Create Team](/docs/endpoints/v3/create-team)). When omitted, the
        request runs as the team that owns the API key.
      schema:
        type: string
  schemas:
    ProfileV3:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the profile
          format: uuid
        lists:
          type: array
          items:
            $ref: '#/components/schemas/PipelineV3'
          description: The lists of the profile
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagV3'
          description: The tags of the profile
        profile_info:
          $ref: '#/components/schemas/ProfileInfoV3'
        found_by:
          $ref: '#/components/schemas/ProfileFoundByV3'
      required:
        - id
    PipelineV3:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the pipeline
        name:
          type: string
          description: The name of the pipeline
        status:
          type: string
          description: The status of the pipeline
      required:
        - id
        - name
        - status
    TagV3:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the tag
        name:
          type: string
          description: The name of the tag
      required:
        - id
        - name
    ProfileInfoV3:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the profile
          format: uuid
        full_name:
          type: string
          description: The full name of the profile
        first_name:
          type: string
          description: The first name of the profile
        last_name:
          type: string
          description: The last name of the profile
        headline:
          type: string
          description: The title of the current job
        about:
          type: string
          description: The industry of the profile
        linkedin_url:
          type: string
          description: The LinkedIn URL of the profile
        work_email:
          type: string
          description: The work email of the profile
        personal_emails:
          type: array
          items:
            type: string
          description: The personal emails of the profile
        current_title:
          type: string
          description: The title of the current job
        current_function:
          type: string
          description: The role of the title in the current job
        current_seniorities:
          type: array
          items:
            type: string
          description: The person's seniority in the current job
        current_company_id:
          type: string
          description: The unique identifier of the company in the current job
          format: uuid
        current_company_name:
          type: string
          description: The name of the company in the current job
        current_company_logo_url:
          type: string
          description: The logo URL of the company in the current job
        current_company_size:
          $ref: '#/components/schemas/SizeClass'
        current_company_location:
          type: string
          description: The location name of the company in the current job
        current_company_linkedin_url:
          type: string
          description: The LinkedIn URL of the company in the current job
        experience:
          type: array
          items:
            $ref: '#/components/schemas/JobV3'
          description: The experience of the profile
        current_location:
          type: string
          description: The location name of the profile
        location_locality:
          type: string
          description: The locality (city) of the profile location
        location_region:
          type: string
          description: The region (state) of the profile location
        location_country:
          type: string
          description: The country of the profile location
        location_continent:
          type: string
          description: The continent of the profile location
        skills:
          type: array
          items:
            type: string
          description: The skills of the profile
        education:
          type: array
          items:
            $ref: '#/components/schemas/EducationV3'
          description: The education of the profile
        social_media:
          type: array
          items:
            $ref: '#/components/schemas/ProfileSocialMedia'
          description: Social media profiles
        smart_tags:
          type: array
          items:
            type: string
          description: AI-generated tags for the profile
        latest_role_change_at:
          type: string
          format: date
          description: The date of the latest role change
        latest_company_change_at:
          type: string
          format: date
          description: The date of the latest company change
        current_job_updated_at:
          type: string
          format: date-time
          description: The update date of current job in the profile
        updated_at:
          type: string
          format: date-time
          description: The update date of the profile
        created_at:
          type: string
          format: date-time
          description: The creation date of the profile
        last_refresh_at:
          type: string
          format: date-time
          description: The last refresh date of the profile
        current_company_websites:
          type: array
          items:
            type: string
          description: The websites of the company in the current job
        current_company_industries:
          type: array
          items:
            type: string
          description: The industries of the company in the current job
        certifications:
          type: array
          items:
            $ref: '#/components/schemas/Certification'
          description: The certifications of the profile
        image_url:
          type: string
          description: Profile image URL (CDN)
        hiring:
          type: boolean
          description: Whether the person is hiring
        open_to_work:
          type: boolean
          description: Whether the person is open to work
      required:
        - id
    ProfileFoundByV3:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
            format: uuid
        linkedin_names:
          type: array
          items:
            type: string
        linkedin_ids:
          type: array
          items:
            type: integer
        linkedin_entity_ids:
          type: array
          items:
            type: string
      description: Which of the requested identifiers matched this result
    ErrorResponse:
      type: object
      properties:
        code:
          description: Error status code
          type: integer
        errors:
          type: array
          items:
            type:
              - string
              - object
      required:
        - code
    SizeClass:
      type: object
      properties:
        min:
          type: integer
          description: The minimum size of the class
        max:
          type: integer
          description: The maximum size of the class
    JobV3:
      type: object
      properties:
        is_current:
          type: boolean
          description: Whether the job is primary or not
        company_id:
          type: string
          description: The unique identifier of the company in the job
          format: uuid
        company:
          $ref: '#/components/schemas/JobCompanyV3'
        title:
          type: string
          description: The title of the job
        seniorities:
          type: array
          items:
            type: string
          description: The person's seniority in the job
        function:
          type: string
          description: The role/function in the job
        location:
          type: array
          items:
            type: string
          description: Job location names
        description:
          type: string
          description: The description of the job
        start_date:
          type: string
          format: date
          description: The start date of the job
        end_date:
          type: string
          format: date
          description: The end date of the job
        status:
          type: string
          description: Experience status enum
          enum:
            - unknown
            - past
            - ongoing
        start_date_confidence:
          type: string
          enum:
            - validated
            - low
          description: Confidence of the experience start date
      required:
        - status
    EducationV3:
      type: object
      properties:
        school:
          $ref: '#/components/schemas/SchoolV3'
        start_date:
          type: string
          format: date
          description: The start date of the education
        end_date:
          type: string
          format: date
          description: The end date of the education
        degrees:
          type: array
          items:
            type: string
          description: The degrees of the education
        majors:
          type: array
          items:
            type: string
          description: The majors of the education
        activities:
          type: string
          description: The activities of the education
        grade:
          type: string
          description: The grade of the education
        description:
          type: string
          description: The description of the education
    ProfileSocialMedia:
      type: object
      properties:
        network:
          type: string
          description: Social media network name
        id:
          type: string
          description: Identifier on the social network
        entity_id:
          type: string
          description: Persistent entity identifier on the social network
        url:
          type: string
          description: Full profile URL
        connections:
          type: integer
          description: Number of connections on the social network
        followers:
          type: integer
          description: Number of followers on the social network
        slug:
          type: string
          description: Slug / handle on the social network
        join_date:
          type: string
          description: Date the profile joined the network (YYYY-MM-DD)
        url_status:
          type: string
          description: Status of the resolved URL
          enum:
            - ''
            - unknown
            - active
    Certification:
      type: object
      properties:
        end_date:
          type: string
          description: The end / expiry date of the certification
        name:
          type: string
          description: The name of the certification
        organization:
          type: string
          description: The issuing organization
        start_date:
          type: string
          description: The start / issue date of the certification
    JobCompanyV3:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the company
        canonical_name:
          type: string
          description: The canonical name of the company
        name:
          type: string
          description: The name of the company
        founded:
          type: string
          format: date-time
          description: The founding date of the company
        size:
          $ref: '#/components/schemas/SizeClass'
        social_media:
          type: array
          items:
            $ref: '#/components/schemas/CompanySocialMedia'
          description: The networks of the company
        locations:
          type: array
          items:
            $ref: '#/components/schemas/CompanyLocationV3'
          description: The locations of the company
        industries:
          type: array
          items:
            type: string
          description: The industries of the company
        websites:
          type: array
          items:
            type: string
          description: The websites of the company
        logo_url:
          type: string
          description: Company logo URL (CDN)
    SchoolV3:
      type: object
      properties:
        name:
          type: string
          description: The name of the school
        location:
          $ref: '#/components/schemas/LocationV3'
        website:
          type: string
          description: The website of the school
        linkedin_url:
          type: string
          description: Linkedin profile URL of the school
        linkedin_id:
          type: integer
          description: Linkedin numeric id of the school
    CompanySocialMedia:
      type: object
      properties:
        network:
          type: string
          description: Social media network name
        id:
          type: string
          description: Identifier on the social network
        slug:
          type: string
          description: Slug / handle on the social network
        url:
          type: string
          description: Full profile URL
    CompanyLocationV3:
      type: object
      properties:
        name:
          type: string
          description: The name of the location
        city:
          type: string
          description: The city of the location
        state:
          type: string
          description: The state of the location
        country:
          type: string
          description: The country of the location
        is_primary:
          type: boolean
          description: Whether the location is the primary (headquarter) location
    LocationV3:
      type: object
      properties:
        name:
          type: string
          description: The name of the location
        city:
          type: string
          description: The city of the location
        state:
          type: string
          description: The state of the location
        country:
          type: string
          description: The country of the location
  responses:
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '401':
      description: Unauthorized
    '402':
      description: Payment required - the team's API credit allowance has been exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '403':
      description: Forbidden
    5XX:
      description: Unexpected error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````