# Get Results by ID

`GET /api/session/get_by_id`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [2025-12-01/openapi.json](https://whitecircle.com/docs/2025-12-01/openapi.json)

Retrieve the results of a previously submitted [content check](https://whitecircle.com/docs/2025-12-01/session/check-session.md) request. Use this endpoint to look up policy check results using either your own tracking identifier or the system-generated ID.

## Query Parameters

> [!WARNING]
> You must provide exactly one of the following identifiers: `external_session_id` or `internal_session_id`. Do not pass both.

| Parameter             | Required | Description                                                                                                                                                                     |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `internal_session_id` |  ✓*      | The system-generated UUID returned in the [content check](https://whitecircle.com/docs/2025-12-01/session/check-session.md) response. This is always available, even if you didn't provide an external session ID. |
| `external_session_id` |  ✓*      | Your custom tracking identifier that you passed when [checking content](https://whitecircle.com/docs/2025-12-01/session/check-session.md). Use this if you want to track sessions with your own IDs.               |
| `deployment_id`       |          | Override deployment resolved from API key. Defaults to the deployment associated with your API key.                                                                             |

*Exactly one of `internal_session_id` or `external_session_id` is required.

## Example Requests

Using your external session ID:

```bash
curl -X GET "https://eu.whitecircle.com/api/session/get_by_id?deployment_id=your-deployment-id&external_session_id=user-session-123" \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "whitecircle-version: 2025-12-01"
```

Using the internal session ID:

```bash
curl -X GET "https://eu.whitecircle.com/api/session/get_by_id?deployment_id=your-deployment-id&internal_session_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "whitecircle-version: 2025-12-01"
```

## Response

The endpoint returns a list of check results matching the provided session identifier. Each result includes:

* `flagged` — Whether any policy violations were detected
* `internal_session_id` — The system-generated UUID for the session
* `external_session_id` — Your custom tracking ID (if provided during check)
* `policies` — A map of policy IDs to their status, including whether each policy was violated

> [!TIP]
> If you provided an `external_session_id` during the original check, use it here for easier lookups. Otherwise, store the `internal_session_id` from the check response.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2025-12-01"`.

## Query Parameters

- `deployment_id` (`string | null`, optional): Optional deployment ID to validate session ownership.
- `external_session_id` (`string | null`, optional): Find check results by external session ID (your tracking identifier).
- `internal_session_id` (`string | null`, optional): Find check results by internal session ID (system-generated UUID).

## Request example

```bash
curl --request GET \
  --url 'https://eu.whitecircle.com/api/session/get_by_id?external_session_id=<external_session_id>' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2025-12-01'
```

## Response

### 200

Success

`application/json`

- `list` (`object[]`, required)
- `list.flagged` (`boolean`, required)
- `list.internal_session_id` (`string`, required)
- `list.policies` (`object`, required)
- `list.policies.{key}` (`object`, optional)
- `list.policies.{key}.flagged` (`boolean`, required)
- `list.policies.{key}.flagged_source` (`enum<string>[]`, required): Available options: `text`, `image`.
- `list.policies.{key}.name` (`string`, required)
- `list.external_session_id` (`string | null`, optional)
- `list.note` (`string | null`, optional)

**Example**

```json
{
  "list": [
    {
      "flagged": true,
      "internal_session_id": "123e4567-e89b-12d3-a456-426614174000",
      "external_session_id": "user-session-001",
      "policies": {
        "70289e06-9111-463e-b121-7247c2b7bfbd": {
          "flagged": true,
          "flagged_source": [
            "text"
          ],
          "name": "No PII Sharing"
        }
      }
    }
  ]
}
```

### 400

Bad Request
