---
title: "Get Packages by PURL"
method: POST
path: "/purl"
tags: ["packages"]
deprecated: true
---

# Get Packages by PURL

`POST /purl`

## Request

- Base URL: `https://api.socket.dev/v0`
- URL: `https://api.socket.dev/v0/purl`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

> **Deprecated.**

**This endpoint is deprecated.** Deprecated since 2026-01-05.

Batch retrieval of package metadata and alerts by PURL strings. Compatible with CycloneDX reports.

Package URLs (PURLs) are an ecosystem agnostic way to identify packages.
CycloneDX SBOMs use the purl format to identify components.
This endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings, or by passing an entire CycloneDX report.

**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.

More information on purl and CycloneDX:

- [`purl` Spec](https://github.com/package-url/purl-spec)
- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)

This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).
Actively running analysis will be returned when available on subsequent runs.

When `alerts=true`, Socket may synthesize two alert types to make partial
results actionable:

- `pendingScan`: the package is known but analysis has not completed yet
- `notFound`: Socket could not resolve the package/version metadata

When `purlErrors=true`, unresolved `notFound` inputs keep the legacy
`purlError` stream shape instead of emitting synthetic `notFound`
artifacts.

Use `poll=false` (default) to fail open and return the current known state
quickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for
pending analysis before returning.

**Conda (temporary compatibility):** `pkg:conda` inputs are served from the
already-scanned PyPI package with the same normalized name and version when
one exists; the response row keeps the original conda PURL in `inputPurl`
but reports `type: pypi`. Conda `build`, `subdir`, `type`, and `channel`
qualifiers are ignored, and conda packages without a scanned PyPI
counterpart return the normal `notFound` result. This mapping will be
replaced by native conda support.

## Examples:

### Looking up an npm package:

```json
{
  "components": [
    {
      "purl": "pkg:npm/express@4.19.2"
    }
  ]
}
```

### Looking up an PyPi package:

```json
{
  "components": [
    {
      "purl": "pkg:pypi/django@5.0.6"
    }
  ]
}
```

### Looking up a Maven package:

```json
{
  "components": [
    {
      "purl": "pkg:maven/log4j/log4j@1.2.17"
    }
  ]
}
```

### Batch lookup

```json
{
  "components": [
    {
      "purl": "pkg:npm/express@4.19.2"
    },
    {
      "purl": "pkg:pypi/django@5.0.6"
    },
    {
      "purl": "pkg:maven/log4j/log4j@1.2.17"
    }
  ]
}
```

This endpoint consumes 100 units of your quota.

This endpoint requires the following org token scopes:
- packages:list

## Query parameters

- `alerts` boolean
- `actions` string[]
- `compact` boolean
- `mode` 'default' | 'compact' | 'firewall-check'
- `fixable` boolean
- `licenseattrib` boolean
- `licensedetails` boolean
- `purlErrors` boolean
- `poll` boolean
- `cachedResultsOnly` boolean
- `summary` boolean
- `timeoutSec` integer

## Request body

- SocketOrgBatchPURLFetch
  - `components` SocketBatchPURLRequest[], required
    - `purl` string, required

## Response `200`

Socket issue lists and scores for all packages, and optional metadata objects

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Insufficient max_quota for API method
- `404`: Resource not found
- `429`: Insufficient quota for API route

## Changes

- **2026-11-03** `5ad8bf36b1e7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/socket-dev/apis/socket/changes/purl/post.md)

---

[API](https://skmtc.dev/socket-dev/apis/socket.md) - [All operations](https://skmtc.dev/socket-dev/apis/socket/llms.txt) - [OpenAPI document](https://skmtc.dev/socket-dev/apis/socket/revisions/5ad8bf36b1e7?raw)