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:
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 yetnotFound: 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.
Examples:
Looking up an npm package:
{
"components": [
{
"purl": "pkg:npm/[email protected]"
}
]
}Looking up an PyPi package:
{
"components": [
{
"purl": "pkg:pypi/[email protected]"
}
]
}Looking up a Maven package:
{
"components": [
{
"purl": "pkg:maven/log4j/[email protected]"
}
]
}Batch lookup
{
"components": [
{
"purl": "pkg:npm/[email protected]"
},
{
"purl": "pkg:pypi/[email protected]"
},
{
"purl": "pkg:maven/log4j/[email protected]"
}
]
}This endpoint consumes 100 units of your quota.
This endpoint requires the following org token scopes:
- packages:list
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
License Attribution
License attribution information for a resource at a given PURL can be requested by setting the query parameter licenseattrib=true. License attribution information is returned as a JSON object in the following format:
attribText: string
attribData: Array<{
purl: string,
foundInFilepath?: string
spdxExpr: string,
foundAuthors: Array<string>
}>- The
attribTextattribute contains the contents of the license that was found, or the model text of the license if the license information was found via package metadata. For example, if an npm package contains a LICENSE file with slight modifications inserting the actual author names and copyright dates, the precise contents of that LICENSE file will occupy theattribTextfield, but if the license information concerns the presence of an SPDX identifierMITin the package.json file,attribTextwill contain the base text of the MIT license. - The
attribDataattribute is an array with one element for each occurrence of the license text in question. Because an identical license text may be used an arbitrary number of times in a large code base, this helps keep the size of responses manageable. Thepurlattribute corresponds to thepurlof the resource in which this license information was found, whilefoundInFilepathcontains the relative path to the location of the license information within the resource (package or artifact).foundInFilepathmay be null if the license information was gleaned from resource metadata.spdxExprcontains an SPDX expression describing the license content.foundAuthorsis an array of additional author information found which is relevant to that particular appearance/instance of the license. For example, if a python package has a pyproject.toml file which identifies the MIT license and contains an array of author names and email addresses, the array entry for that particularattribDatawill have a purl pointing to that package/artifact, a relative path to the pyproject.toml file, an SPDX expression identifying the MIT license, and an array containing the author information present in the pyproject.toml file.
License Details
More fine-grained details concerning license identification can be requested by setting the query parameter licensedetails=true. License details are returned as a JSON object in the following format:
spdxDisj: string
provenance: string
filepath?: string
match_strength: float- The
spdxDisjattribute contains an SPDX expression identifying the license match - The
provenanceattribute contains information concerning the provenance of the license data (in a more detailed sense than just resource path, where did we find this license info?) - The
filepathattribute contains a relative path to the resource used to identify this license information if it exists (for license information taken from something like package metadata, there may not be an appropriate filepath) - The
match_strengthproperty contains a value between 0 and 1 describing the strength of the license match (0 for no similarity, 1 for identical contents). For license data found by examining SPDX expressions, this property will be1.
