# SAM.gov · Search

Search public records with SAM.gov · Search from Alexandria through one Spiral API key. Search SAM.gov contract opportunities by keyword, agency, notice status, publication date, NAICS, set-aside, notice type and response deadline. Returns one page (default 20, max 100) with an opaque cursor for the next page. It runs in the background and returns structured JSON. Pay as you go, with no subscription.

- Provider: Alexandria
- Category: Public Records
- Runs: In the background
- Returns: json
- Tool id: `alexandria` / `sam-gov/opportunities/search`
- Page: https://spiral.ai/tools/alexandria/sam-gov/opportunities/search

## Pricing

$0.00873 per call.

## Limits

- Longest queue wait: 1 hour
- Run deadline: 5 minutes
- Longest run, end to end: 225 minutes
- Largest inline input: 1 MB
- Largest input file: 2 GB
- Largest output: 5 GB

## Input

| Field | Kind | Allowed | Default | Description |
| --- | --- | --- | --- | --- |
| `sort` | one of | updated_desc, updated_asc, relevance, deadline_asc, deadline_desc | updated_desc | sort |
| `query` | text |  |  | Keyword query matched against title, solicitation number and description. Multi-word queries combine per query_mode (default: every word must match). Empty matches everything. |
| `cursor` | text |  | — | Opaque cursor from a previous response's next_cursor. Bound to the same filters and page_size; valid for 24 hours; then cursor_expired. |
| `statuses` | list |  | — | Notice status as SAM.gov indexes it. active = accepting responses / not yet archived; inactive = archived. Both = no status filter. |
| `page_size` | number | 1 to 100 | 20 | Records per page. At most 50 when include_attachments is true. |
| `agency_ids` | list |  | — | SAM.gov federal organization ids at any hierarchy level (100000000 = Dept of Defense, 300000188 = Dept of the Navy, 100006688 = Dept of Veterans Affairs). Matched as OR. |
| `query_mode` | one of | all, any, exact | all | How the words of query must match, as SAM.gov's own keyword search offers them (upstream qMode): all = every word (SAM.gov's default), any = at least one word, exact = the phrase as written. |
| `set_asides` | list |  | — | SAM.gov set-aside codes (SBA = total small business, 8A, HZC = HUBZone, SDVOSBC, WOSB, EDWOSB, ...). Matched as OR. |
| `naics_codes` | list |  | — | NAICS codes or prefixes (2 to 6 digits). Matched as OR. |
| `notice_types` | list |  | — | Notice types (SAM.gov codes p,o,k,a,r,s,i,g,u,f,l). Empty = all. |
| `published_to` | text |  | — | Inclusive upper bound (YYYY-MM-DD). Must not be before published_from. Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$. |
| `published_from` | text |  | — | Inclusive lower bound (YYYY-MM-DD, US Eastern calendar day) on the notice's latest publication/modification date. Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$. |
| `include_details` | true or false |  | — | Fetch each hit's notice detail (one extra upstream request per record) so naics_codes, set_aside, place_of_performance and the full description are populated. false returns summary records with detail_level=summary. |
| `include_attachments` | true or false |  | — | Also list each notice's attachments (one more upstream request per record). Requires include_details and page_size <= 50. |
| `response_deadline_to` | text |  | — | Inclusive upper bound (YYYY-MM-DD) on the response deadline. |
| `response_deadline_from` | text |  | — | Inclusive lower bound (YYYY-MM-DD) on the response deadline. |

## Example

```bash
curl https://api.spiral.ai/v1/runs \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "provider": "alexandria",
    "model": "sam-gov/opportunities/search",
    "input": {
      "sort": "updated_desc"
    }
  }'
```

Try it in the Playground: https://spiral.ai/start?provider=alexandria&model=sam-gov%2Fopportunities%2Fsearch

## Common questions

### SAM.gov · Search

**How much does SAM.gov · Search cost?**

$0.00873 per call. You pay as you go from one Spiral balance, with no subscription, and a failed run is not charged.

**How do I use SAM.gov · Search through an API?**

Send `POST /v1/runs` with `"provider": "alexandria"`, `"model": "sam-gov/opportunities/search"` and the input fields on this page, using one Spiral API key. It runs in the background: poll the run, or name a webhook to be told when it finishes.

**Do I need an account with Alexandria to use SAM.gov · Search?**

No. Spiral runs it on its own Alexandria account and charges your Spiral balance.

**Can my AI agent use SAM.gov · Search?**

Yes. Agents find and run it through Spiral's MCP server, CLI or agent skill, with the same API key.

