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

# Get Subjects by External ID

> Retrieve subjects by their external ID and type

## Query Parameters

<ParamField query="type" type="string" required>
  Subject type. One of: `user`, `api_key`, `service`, `agent`
</ParamField>

<ParamField query="externalId" type="string" required>
  The external identifier to search for
</ParamField>

## Response

Returns an array of subjects matching the external ID and type.

<ResponseField name="subjects" type="array">
  <Expandable title="Subject object">
    <ResponseField name="id" type="string">
      Unique identifier for the subject
    </ResponseField>

    <ResponseField name="type" type="string">
      Subject type
    </ResponseField>

    <ResponseField name="externalId" type="string">
      External identifier
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.example.com/subjects/by-external?type=user&externalId=user-456' \
    -H 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const { data } = await axios.get('https://api.example.com/subjects/by-external', {
    params: { type: 'user', externalId: 'user-456' },
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": "sub_123",
      "type": "user",
      "externalId": "user-456",
      "metadata": {}
    }
  ]
  ```
</ResponseExample>