# WebSocket stream wss://stream.samgovapi.io/v1/stream pushes a JSON event the moment a load changes an opportunity, award, exclusion or entity, filtered by NAICS, agency, state and set-aside, on every plan: Free 5 minutes late with opportunities and exclusions, Developer and Pro in real time, Scale with your alert firings too. Authenticate with the same API key; resume with after=<cursor> for 14 days.Checked on 2026-11-12.Official source: [RFC 6455 WebSocket](https://www.rfc-editor.org/rfc/rfc6455) | URL | wss://stream.samgovapi.io/v1/stream | | --- | --- | | Plans | All; Free 5 min late | | Auth | Authorization: Bearer or an auth message | | Resume | after=, 14 days | | Health | https://stream.samgovapi.io/healthz | ## Plans Every plan streams. Free: opportunities and exclusions, 5 minutes late, 1 connection. Developer (2) and Pro (3 connections): every record change in real time. Scale: also your alert firings, 5 connections. | Plan | Delivery | Datasets | Connections | | --- | --- | --- | --- | | Free | 5 minutes | opportunity, exclusion | 1 | | Developer | Real time | opportunity, award, exclusion, entity | 2 | | Pro | Real time | opportunity, award, exclusion, entity | 3 | | Scale | Real time | opportunity, award, exclusion, entity, alert | 5 | ## When events arrive Events are pushed the moment a load commits a change. The sources themselves refresh on a schedule: opportunities once a day (about 05:15 UTC), exclusions daily (about 05:45 UTC), awards twice a day (07:00 and 15:00 UTC), entities monthly. So the stream removes polling, not the source's own delay. ## Events | Event | When | | --- | --- | | opportunity.created / .updated / .closed | A notice appears in the SAM.gov file, changes (amendment, new deadline, award details), or drops out of the active file | | award.created / .updated | A USAspending contract award or modification is loaded or revised | | exclusion.created / .updated / .removed | A firm's exclusion appears, changes or leaves the daily extract (individuals are never streamed) | | entity.created / .updated / .removed | A registration appears, changes or leaves the monthly extract (opt in with types=entity; individuals are never streamed) | | alert.registration_expiry / .opportunity_match / .recompete / .exclusion | One of your saved alerts fires (Scale; live only, no replay) | ## Filters | Query parameter | Meaning | | --- | --- | | types | Datasets (opportunity, award, exclusion, entity, alert) or exact event types, comma-separated. Default: opportunity, award, exclusion, alert, narrowed to what your plan streams. | | naics | NAICS codes or prefixes, comma-separated (5415 matches 541511 and 541512). | | agency | Agency name fragments, comma-separated, case-insensitive (defense, veterans affairs). | | state | Two-letter place-of-performance or address states, comma-separated. | | set_aside | Set-aside codes, comma-separated (SBA, 8A, SDVOSBC, WOSB, HZC). | | after | The cursor of the last event you processed: replays everything since, for up to 14 days. | ## Connection rules - Authenticate with Authorization: Bearer sg_... on the upgrade request (servers), or send {"type":"auth","api_key":"sg_..."} as the first message within 5 seconds (browsers). A key in the URL is refused. - The first message is {"type":"connected","plan","cursor","filters","delay_seconds","max_connections",...}; on Free it also carries an upgrade hint. Each event is {"type","cursor","key","at","data"}; store cursor after you process it. - A {"type":"heartbeat","cursor"} message arrives every 30 seconds and the server pings every 20 seconds. If nothing arrives for 60 seconds, reconnect. - Reconnect with exponential backoff (1, 2, 4 ... 60 seconds) and after=; nothing is lost within 14 days. - Opening a connection is free. Delivered events cost 1 credit per 100, charged every 5 minutes, when the key is also checked again: a revoked key is disconnected, and a plan change closes with 1012 so you reconnect under the new plan. - Free gets each event 5 minutes after it is written, in order; a new Free connection starts 5 minutes back, so events flow at once. Developer, Pro and Scale get events as they commit. ## Node ``` // npm install ws import WebSocket from "ws"; let cursor = null; // persist this to resume after a restart let backoff = 1; function connect() { const params = new URLSearchParams({ types: "opportunity,award", naics: "5415" }); if (cursor) params.set("after", cursor); const ws = new WebSocket(`wss://stream.samgovapi.io/v1/stream?${params}`, { headers: { Authorization: `Bearer ${process.env.SAMGOVAPI_API_KEY}` }, }); let idle; const touch = () => { clearTimeout(idle); idle = setTimeout(() => ws.terminate(), 60_000); }; ws.on("open", () => { backoff = 1; touch(); }); ws.on("message", (raw) => { touch(); const msg = JSON.parse(raw); if (msg.type === "error") return console.error(msg.code, msg.message); if (msg.type === "connected" || msg.type === "heartbeat") return; console.log(msg.type, msg.key, msg.data.title ?? msg.data.recipient_name ?? msg.data.name); if (msg.cursor) cursor = msg.cursor; }); ws.on("close", (code) => { clearTimeout(idle); if ([4401, 4402, 4403].includes(code)) return; // fix the key or plan first setTimeout(connect, backoff * 1000); backoff = Math.min(backoff * 2, 60); }); ws.on("error", () => {}); } connect(); ``` ## Python ``` # pip install websockets import asyncio, json, os import websockets API_KEY = os.environ["SAMGOVAPI_API_KEY"] cursor = None # persist this to resume after a restart async def main(): global cursor backoff = 1 while True: url = "wss://stream.samgovapi.io/v1/stream?types=opportunity,award&naics=5415" if cursor: url += f"&after={cursor}" try: async with websockets.connect( url, additional_headers={"Authorization": f"Bearer {API_KEY}"}, ping_interval=20 ) as ws: backoff = 1 while True: msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=60)) if msg["type"] == "error": print(msg["code"], msg["message"]) elif msg["type"] not in ("connected", "heartbeat"): print(msg["type"], msg["key"]) cursor = msg.get("cursor") or cursor except websockets.ConnectionClosed as e: if e.rcvd and e.rcvd.code in (4401, 4402, 4403): raise # fix the key or plan first except (OSError, asyncio.TimeoutError): pass await asyncio.sleep(backoff) backoff = min(backoff * 2, 60) asyncio.run(main()) ``` ## Event shape ``` { "type": "opportunity.created", "cursor": "184467", "key": "3f1c9a0e2b7d4c55a1e0f9b8c7d6e5f4", "at": "2026-11-20T05:16:02.114Z", "data": { "notice_id": "3f1c9a0e2b7d4c55a1e0f9b8c7d6e5f4", "title": "Cybersecurity Operations Support", "type": "Combined Synopsis/Solicitation", "department": "DEPT OF DEFENSE", "naics": "541512", "set_aside_code": "SBA", "response_deadline": "2026-12-05T21:00:00.000Z", "pop_state": "VA", "active": true, "url": "https://samgovapi.io/opportunity/3f1c9a0e2b7d4c55a1e0f9b8c7d6e5f4" } } ``` ## Close codes | Code | Error | Meaning | | --- | --- | --- | | 4400 | invalid_query | A filter is malformed, or the key was put in the URL. | | 4401 | INVALID_API_KEY | Unknown, revoked or malformed key, or a suspended account. | | 4402 | QUOTA_EXCEEDED | Monthly credits are used up. | | 4403 | PLAN_REQUIRED | Every asked-for type needs a higher plan (award and entity: Developer; alert: Scale). Asking for some is fine: the rest stream and a notice names what was left out. | | 4408 | auth_timeout | No auth message within 5 seconds. | | 4409 | slow_consumer | The client fell more than 8 MB behind. Reconnect with after. | | 4429 | STREAM_LIMIT_EXCEEDED | More open connections than the plan allows (Free 1, Developer 2, Pro 3, Scale 5), or the per-minute request limit. | | 4503 | service_unavailable | Temporary. Reconnect with backoff and after. | | 1012 | restart | The gateway is restarting. Reconnect at once with after. | ## Questions Is there a SAM.gov WebSocket API?SAM.gov's own APIs are REST only, with daily request limits. wss://stream.samgovapi.io/v1/stream is a WebSocket over the same public data, run by this independent service.Do I need webhooks too?No. Webhooks POST alert firings to your HTTPS endpoint; the WebSocket carries every record change (and, on Scale, your alert firings) over a connection you open. Use whichever fits your stack.What happens if I disconnect?Reconnect with after set to the cursor of the last event you processed. Every change from the last 14 days is replayed in order before live events resume. ## Related - [Webhooks](https://samgovapi.io/docs/webhooks) - [Alerts](https://samgovapi.io/docs/alerts) - [Pricing](https://samgovapi.io/pricing)Updated 2026-11-12. Sources checked 2026-11-12.Independent. Not affiliated with, endorsed by or sponsored by GSA, SAM.gov or any U.S. government agency. Registering in SAM.gov is free at sam.gov.

---

HTML version: https://samgovapi.io/docs/websocket . Markdown: https://samgovapi.io/docs/websocket.md

Independent. Not affiliated with, endorsed by or sponsored by GSA, SAM.gov or any U.S. government agency. Registering in SAM.gov is free at sam.gov.

Get a free API key: https://samgovapi.io/sign-up?ref=ai-claudebot
