SAM APIsam.gov ↗
Search and retrieve federal contract opportunity notices from SAM.gov. Access notice details, NAICS codes, award data, attachments, and revision history.
What is the SAM API?
This API provides access to SAM.gov federal contract opportunity notices across 3 endpoints. Use search_opportunities to run keyword searches against notice titles, descriptions, and solicitation numbers with optional NAICS code filtering, notice type filtering, and response deadline sorting. Full notice details — including award data, place of performance, points of contact, and complete HTML or plain-text descriptions — are available via get_opportunity.
curl -X GET 'https://api.parse.bot/scraper/cc787065-d91e-4a91-a013-e892af2fabfe/search_opportunities?page=2&size=5&sort=modified_date&query=cybersecurity&status=all¬ice_type=o' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace sam-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: SAM.gov contract opportunities — search, drill down, list attachments."""
from parse_apis.sam_gov_api import SamGov, SortOrder, NoticeType, InputNotFound
client = SamGov()
# Search active opportunities by keyword, capped to 5 total results.
for summary in client.opportunity_summaries.search(
query="cybersecurity",
sort=SortOrder.MODIFIED_DATE,
notice_type=NoticeType.SOLICITATION,
limit=5,
):
print(summary.title, summary.organization.agency, summary.notice_type)
# Drill into the first result's full details via the typed summary→detail link.
summary = client.opportunity_summaries.search(query="cybersecurity", limit=1).first()
if summary is not None:
opp = summary.details()
print(opp.title, opp.status, opp.solicitation_number)
print("NAICS:", opp.naics_codes)
print("Place:", opp.place_of_performance.city, opp.place_of_performance.state)
# Walk points of contact on the full opportunity.
for contact in opp.points_of_contact:
print(contact.full_name, contact.email)
# List attached documents for this opportunity.
for att in opp.attachments.list(limit=10):
print(att.name, att.size_bytes, att.download_url)
# Point lookup by an id discovered from the search above.
if summary is not None:
try:
detail = client.opportunities.get(opportunity_id=summary.opportunity_id)
print(detail.title, detail.response_deadline)
except InputNotFound:
print("Opportunity no longer available")
print("exercised: search / details / get / attachments.list")
Keyword search over SAM.gov contract opportunity notices. Returns one page of notice summaries (title, notice type, dates, issuing organization, description snippet) plus total_results and total_pages from the site. Paging is caller-controlled: page (1-based, default 1) and size (1-100, default 25); has_more is true while page < total_pages. By default only active notices are returned; status widens to inactive or all. notice_type filters to a single notice type code, naics to a NAICS code prefix (2-6 digits). Sorting defaults to the site's relevance ranking. Keyword match mode defaults to all words. An empty results array with total_results 0 is a valid response for a term with no matches.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based results page. |
| size | integer | Results per page, 1-100. |
| sort | string | Result ordering: relevance ranking, most recently updated first, or soonest response deadline first. |
| naics | string | NAICS code or code prefix, 2-6 digits (e.g. 541512). Omitted = no NAICS filter. |
| queryrequired | string | Natural-language keyword search text; matched against notice titles, descriptions, and solicitation numbers. |
| status | string | Whether to return only active notices, only inactive (archived/closed) notices, or both. |
| match_mode | string | How the keywords are matched: all words present, any word present, or the exact phrase. |
| notice_type | string | Single notice type code to restrict results to. Omitted = all notice types. |
{
"type": "object",
"fields": {
"page": "1-based page returned",
"size": "page size used",
"query": "echo of the search text",
"results": "array of notice summaries; opportunity_id is the key accepted by get_opportunity and list_opportunity_attachments",
"has_more": "boolean, true when a later page exists",
"total_pages": "integer total pages at this size",
"total_results": "integer total matching notices reported by the site",
"results[].organization": "object with department, agency, office names of the issuing office (nulls when the site omits a level)",
"results[].response_date": "ISO datetime with offset of the response deadline, null when the notice has none",
"results[].notice_type_code": "single-letter SAM.gov notice type code (see NoticeType enum)",
"results[].modification_count": "integer number of published revisions"
},
"sample": {
"data": {
"page": 1,
"size": 5,
"query": "cybersecurity",
"results": [
{
"url": "https://sam.gov/workspace/contract/opp/6c70e76fce4e449087a6b90f656b6d87/view",
"title": "Cyber Platform",
"is_active": true,
"is_canceled": false,
"notice_type": "Presolicitation",
"organization": {
"agency": "DEPT OF THE NAVY",
"office": "NAVSUP FLT LOG CTR NORFOLK",
"department": "DEPT OF DEFENSE"
},
"modified_date": "2026-08-18T14:06:51+00:00",
"response_date": null,
"opportunity_id": "6c70e76fce4e449087a6b90f656b6d87",
"published_date": "2026-08-18T14:06:51+00:00",
"notice_type_code": "p",
"response_timezone": null,
"modification_count": 0,
"description_snippet": "NAVSUP Fleet Logistics Center Norfolk, Contracting Department, Pentagon Directorate intends to acquire, via small business set aside, a commercial cybersecurity training and certification platform for National Defense University (NDU), College of",
"solicitation_number": "N0018926QD213"
}
],
"has_more": true,
"total_pages": 169,
"total_results": 842
},
"status": "success"
}
}About the SAM API
Search and Filter Contract Notices
search_opportunities accepts a required query string matched against notice titles, descriptions, and solicitation numbers on SAM.gov. Results can be filtered by naics code (2–6 digit prefix), notice_type code, and status (active, inactive, or both). The match_mode parameter controls whether the query matches all words, any word, or an exact phrase. Each result in the results array includes an opportunity_id — a 32-character hex identifier used by the other two endpoints — along with response_date, notice_type_code, and an organization object containing department, agency, and office names.
Full Notice Details
get_opportunity takes an opportunity_id and returns the complete record: naics_codes, set_aside_code, archive_date, status, and the full description in both description_html and description_text. When the notice is a contract award, the award object includes date, number, amount, awardee_name, and awardee_uei. The history array lists all revisions of the notice, newest first, each with its own opportunity_id, index, request_type, action_type, posted_date, and notice_type.
Attachments and Documents
list_opportunity_attachments returns all documents and external links attached to a notice in the site's display order. Each record in the attachments array includes type (file or link), size_bytes, download_url for uploaded files, uri for external links, and is_deleted to flag removed attachments. The attachment_count field gives the total count without iterating the array. File contents are not fetched — only the public SAM.gov download URL is returned.
The SAM API is a managed, monitored endpoint for sam.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when sam.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official sam.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor new federal contract solicitations matching a specific NAICS code prefix for market intelligence
- Track response deadline changes by comparing
response_dateacross repeated searches on the same solicitation - Build a procurement pipeline tool that surfaces active set-aside opportunities using
set_aside_codeandstatusfilters - Retrieve full award records including
awardee_name,awardee_uei, andamountfor competitive analysis - Enumerate all attachments on a solicitation notice before downloading RFP documents via their
download_url - Audit notice revision history using the
historyarray to see how a solicitation has changed over time - Filter opportunities to a specific federal agency by inspecting the
organization.agencyfield in search results
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does SAM.gov have an official developer API?+
What does the `history` array in `get_opportunity` contain?+
opportunity_id for that revision, an index, request_type, action_type, posted_date, and notice_type. This lets you reconstruct the amendment history of a solicitation.Does `search_opportunities` return notices from all SAM.gov notice types?+
notice_type parameter, which accepts a single SAM.gov notice type code. Multiple simultaneous notice type filters are not currently supported. You can fork the API on Parse and revise it to add multi-type filtering.Does the API return the actual content of attached files?+
list_opportunity_attachments returns metadata and, for file attachments, a public download_url pointing to the SAM.gov file. The file content itself is not fetched or returned. You can fork the API on Parse and revise it to add an endpoint that retrieves file bytes from the provided URL.Are there any data gaps to be aware of when using `get_opportunity`?+
award object is null for any notice that is not an award notice. set_aside_code and archive_date may be null when the source notice omits them. Organization fields in search results (department, agency, office) may also be null if the issuing office record is incomplete on SAM.gov.