Query the active federal opportunity directory from a script, internal dashboard, or data pipeline. This reference mirrors the shipped GET /api/opportunities route.
Pro access, verified identity
API-key requests require a verified user with an active Pro subscription. The key secret is shown once when you create it.
01 / Authenticate
Create an API key in the Developer API keys panel on your profile page. The full ss_live_… secret appears only once, so store it in your secret manager. Every external request sends the exact header below.
02 / Request
All filters are optional. Query values are URL-encoded, and repeatable parameters such as naics appear once per value. Invalid enum values, negative offsets, or limits outside 1–100 return a 400 response.
qcloud securityCase-insensitive containment in title or solicitationNumber.
departmentDefenseCase-insensitive containment in the department name.
naics541511&naics=541512Repeat the parameter; each value matches an exact NAICS code.
setAsideSBAExact match against the set-aside code.
stateALCase-insensitive, two-character office-state value.
statusall | open | closingall is the default; open means 7+ days out; closing means now through 7 days.
offset0Nonnegative integer offset. Defaults to 0 and is echoed in the response.
limit25Integer from 1 to 100. Defaults to 25 and is echoed in the response.
postedDate descending. A verified Free account can access 50 results; Pro can access 1,000. The response total is capped to that caller ceiling.offset=0, then increase by the requested limit until offset >= total. Pro responses may also include a top-five agencySummary.03 / Copy and run
Replace YOUR-SEARCHSAM-ORIGIN with the deployed SearchSam origin and keep the key out of source control. The encoded query includes every filter family plus a repeatable NAICS parameter.
curl · bearer request
curl --request GET \
--url 'https://YOUR-SEARCHSAM-ORIGIN/api/opportunities?q=cloud%20security&department=Defense&naics=541511&naics=541512&setAside=SBA&state=AL&status=open&offset=0&limit=25' \
--header 'Authorization: Bearer ss_live_your_key_secret'json · representative Pro response
{
"items": [
{
"id": "opp_01J8Q4FJ8Y2K",
"noticeId": "a1b2c3d4e5f6",
"title": "Cloud security operations support",
"solicitationNumber": "W52P1J-26-R-0042",
"department": "Department of Defense",
"subtierName": "Army Contracting Command",
"naicsCode": "541511",
"naicsDescription": "Custom computer programming services",
"typeOfSetAside": "Small Business",
"typeOfSetAsideCode": "SBA",
"opportunityType": "solicitation",
"postedDate": "2026-09-15T13:00:00.000Z",
"responseDeadline": "2026-10-15T17:00:00.000Z",
"officeCity": "Huntsville",
"officeState": "AL",
"active": true,
"uiLink": "https://sam.gov/opp/a1b2c3d4e5f6/view"
},
{
"id": "opp_01J8Q4G2M5LZ",
"noticeId": "f6e5d4c3b2a1",
"title": "Professional services market research",
"solicitationNumber": null,
"department": "Department of Energy",
"subtierName": null,
"naicsCode": "541618",
"naicsDescription": null,
"typeOfSetAside": null,
"typeOfSetAsideCode": null,
"opportunityType": "presolicitation",
"postedDate": "2026-09-14T09:30:00.000Z",
"responseDeadline": null,
"officeCity": null,
"officeState": "DC",
"active": true,
"uiLink": "https://sam.gov/opp/f6e5d4c3b2a1/view"
}
],
"total": 184,
"offset": 0,
"limit": 25,
"feed": "OK",
"feedErrorCode": null,
"lastAttemptAt": "2026-09-19T05:00:00.000Z",
"lastCleanSync": "2026-09-19T05:02:14.000Z",
"activeCount": 184,
"naicsOptions": [
{
"code": "541511",
"description": "Custom computer programming services"
},
{
"code": "541618",
"description": "Other management consulting services"
}
],
"agencySummary": [
{
"agency": "Department of Defense",
"count": 72
},
{
"agency": "Department of Energy",
"count": 31
}
]
}04 / Read the response
The JSON example above includes the complete envelope: items, total, offset, limit, feed diagnostics, timestamps, the active count, NAICS facet options, and the optional Pro agency summary. Nullable fields are returned as null, not omitted.
idSearchSam opportunity identifier.
noticeIdSAM.gov notice identifier.
titleOpportunity title.
solicitationNumberSolicitation number, or null.
departmentParent agency, or null.
subtierNameSub-tier agency, or null.
naicsCodeNAICS code, or null.
naicsDescriptionNAICS description, or null.
typeOfSetAsideSet-aside label, or null.
typeOfSetAsideCodeExact set-aside code, or null.
opportunityTypeSAM.gov opportunity type, or null.
postedDateISO timestamp, or null.
responseDeadlineISO timestamp, or null.
officeCityOffice city, or null.
officeStateOffice state, or null.
activeAlways true for this active directory collection.
uiLinkCanonical SAM.gov link for Pro; null for Free.
uiLink values and may receive the optional top-five agencySummary. Free callers receive uiLink: null and no agency summary.05 / Operate safely
Feed health does not change the list status code. The collection route still returns a 200 envelope when feed is one of the states below; inspect feedErrorCode for a safe diagnostic when it is present.
400 — { "error": "Invalid query parameters" }
401 — { "error": "Unauthorized" } for a malformed, unknown, or revoked bearer key.
403 — { "error": "email_verification_required" } or { "error": "pro_required" }.