How to use the ContractRadar API

Call contract search directly from a script or server instead of through the web app. Requires a Pro subscription.

Getting a token

1. Go to your profile → API Access.
2. Click Generate token.
3. Copy it — it’s shown once and can’t be retrieved again.

The token reads search as you. Treat it like a password: keep it on a server or in a secrets store, never in a browser or a public repo. If one was ever sent over plain http://, regenerate it.

Making a request

Send the token as a bearer token against GET /api/v1/posts:

curl -H "Authorization: Bearer crk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  "https://contractradar.io/api/v1/posts?q=electrical+wiring&state=TX&pageSize=10"

import os
import requests

token = os.environ["CONTRACTRADAR_TOKEN"]
params = {"q": "electrical wiring", "state": "TX", "pageSize": 10}
# repeat a key for more than one value: params["state"] = ["TX", "NM"]

r = requests.get(
    "https://contractradar.io/api/v1/posts",
    headers={"Authorization": f"Bearer {token}"},
    params=params,
)
r.raise_for_status()
items = r.json()["items"]

// Node 18+ ESM (.mjs, or "type": "module"), server-side only — never ship this token to a browser.
const token = process.env.CONTRACTRADAR_TOKEN;
if (!token) throw new Error("CONTRACTRADAR_TOKEN is not set");
const params = new URLSearchParams({ q: "electrical wiring", state: "TX", pageSize: "10" });
// params.append("state", "NM") to add another state

const res = await fetch(`https://contractradar.io/api/v1/posts?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
});
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const { items } = await res.json();

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var token = Environment.GetEnvironmentVariable("CONTRACTRADAR_TOKEN")
    ?? throw new InvalidOperationException("CONTRACTRADAR_TOKEN is not set");
var query = "q=electrical+wiring&state=TX&pageSize=10";
// repeat state=XX&state=YY to filter on more than one

using var client = new HttpClient { BaseAddress = new Uri("https://contractradar.io") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var page = await client.GetFromJsonAsync<JsonElement>($"/api/v1/posts?{query}");
var items = page.GetProperty("items");

Query parameters

All optional.

Only sort, mode, the date parameters, and minScore/maxScore reject a bad value with a 400. An unrecognised postType, buyerType (or coverageType), state or tag is silently ignored — the filter just doesn’t apply, so a typo looks like too many results rather than an error.

Matching mode

By default q is matched semantically: we embed your query and rank contracts by meaning, so q=snow removal also returns “winter road maintenance services”.

mode=literal turns that off and matches literally instead: case-insensitive substring, against the contract’s title or description — and nothing else. Not tags, not agency, not externalId. To filter on a tag, use the tag parameter, which matches exactly. No embedding model is called, so results are entirely determined by the characters you send.

Prefer it when you already know the exact string: a solicitation number, a statute or programme name, an agency’s in-house term of art, a specific material or model. Prefer the default when you are describing a kind of work rather than quoting a phrase — mode=literal with q=snow removal will miss every contract that calls it something else.

q must contain at least 3 consecutive letters or digits in mode=literal — so hv, a b and ab% are all rejected, while abc, a bcd and W912DR-24-R-0043 are fine. A pattern without such a run cannot use the index behind this mode, so it is rejected rather than served slowly. Unlike the default, q in mode=literal is never truncated to 200 characters — a literal match has to be exactly what you sent, so a query that would be silently shortened is rejected instead.

Every other parameter behaves identically in both modes, and a literal search costs the same one search against your daily limit. minScore/maxScore are accepted but ignored: a literal match has nothing to score, since it either contains what you typed or it doesn’t. sort=relevance (the default) has the same caveat — there is no similarity to rank by, so it returns matches newest-first, the same as an unranked browse.

One difference to plan for: a literal search works over at most the 1,000 newest matching contracts (by posted date). A broad term returns totalCount: 1000 with totalIsCapped: true — the same way a semantic search reports its candidate cap — and sort orders those 1,000, so sort=deadline_asc means “soonest deadline among the newest 1,000 matches”. Pages past totalPages are empty. If a term is capped, narrow it with more words or filters rather than paging deeper.

Every *Before bound resolves to 00:00:00Z on the named date and matches up to and including that instant, so updatedBefore=2026-09-20 returns nothing later than midnight on the 20th. To include a whole day, use the next date.

Response shape

{
  "items": [
    {
      "id": "8f14e45f-ceea-467e-bd3e-8f1f4c0e1234",
      "externalId": "SAM-2026-00123",
      "title": "Electrical wiring upgrade — Building 4",
      "agency": "General Services Administration",
      "placeOfPerformanceState": "TX",
      "postedDate": "2026-09-10T00:00:00Z",
      "responseDeadline": "2026-10-01T00:00:00Z",
      "postType": "Contract",
      "contractSource": "SamGov",
      "contractSourceShortLabel": "Fed",
      "contractSourceFullLabel": "Federal Contract",
      "contractSourceAbbreviation": "FED",
      "contractSourcePortalName": "SAM.gov",
      "description": "Upgrade of electrical distribution systems...",
      "link": "https://sam.gov/opp/abc123/view",
      "linksToListingPageOnly": false,
      "tags": [{ "key": "Set-Aside", "value": "WOSB" }],
      "canonicalPostId": "8f14e45f-ceea-467e-bd3e-8f1f4c0e1234",
      "similarityScore": 0.47,
      "buyerType": "Federal"
    }
  ],
  "totalCount": 42,
  "totalPages": 3,
  "page": 1,
  "pageSize": 20,
  "totalIsCapped": false
}

tags is always an array, never null. postType and contractSource serialize as strings, not integers.

Exporting to CSV

GET /api/v1/posts/export returns the whole result set as a CSV file rather than a page of JSON. It takes exactly the same parameters as the search above, and ignores page and pageSize. The response is text/csv with a Content-Disposition filename, not JSON.

curl -D headers.txt -o contracts.csv \
  -H "Authorization: Bearer crk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  "https://contractradar.io/api/v1/posts/export?state=TX&buyerType=City"

# Was it capped? The header is present only when it was.
grep -i x-export-truncated headers.txt

import os
import requests

token = os.environ["CONTRACTRADAR_TOKEN"]

# stream=True — a browse export can be 10,000 rows of description text (~20 MB).
with requests.get(
    "https://contractradar.io/api/v1/posts/export",
    headers={"Authorization": f"Bearer {token}"},
    params={"state": "TX", "buyerType": "City"},
    stream=True,
) as r:
    r.raise_for_status()
    with open("contracts.csv", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

rows = r.headers["X-Export-Row-Count"]
if "X-Export-Truncated" in r.headers:
    print(f"Capped at {rows} rows — narrow the search to get the rest.")

// Node 18+ ESM, server-side only — never ship this token to a browser.
import { writeFile } from "node:fs/promises";

const token = process.env.CONTRACTRADAR_TOKEN;
if (!token) throw new Error("CONTRACTRADAR_TOKEN is not set");
const params = new URLSearchParams({ state: "TX", buyerType: "City" });

const res = await fetch(`https://contractradar.io/api/v1/posts/export?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
});
if (!res.ok) throw new Error(`Export failed: ${res.status}`);

await writeFile("contracts.csv", Buffer.from(await res.arrayBuffer()));

const rows = res.headers.get("X-Export-Row-Count");
if (res.headers.get("X-Export-Truncated")) {
  console.warn(`Capped at ${rows} rows — narrow the search to get the rest.`);
}

using System.Net.Http.Headers;

var token = Environment.GetEnvironmentVariable("CONTRACTRADAR_TOKEN")
    ?? throw new InvalidOperationException("CONTRACTRADAR_TOKEN is not set");

using var client = new HttpClient { BaseAddress = new Uri("https://contractradar.io") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

// ResponseHeadersRead so the headers are available before the whole CSV is buffered.
using var res = await client.GetAsync(
    "/api/v1/posts/export?state=TX&buyerType=City",
    HttpCompletionOption.ResponseHeadersRead);
res.EnsureSuccessStatusCode();

await using (var file = File.Create("contracts.csv"))
    await res.Content.CopyToAsync(file);

var rows = res.Headers.GetValues("X-Export-Row-Count").First();
if (res.Headers.Contains("X-Export-Truncated"))
    Console.WriteLine($"Capped at {rows} rows — narrow the search to get the rest.");

How many rows you get depends on whether you sent a keyword, and the difference is not a policy we set:

So to pull a large set, express it as filters (state, buyerType, postType, tag, and the date ranges) rather than as a keyword.

Two response headers tell you what you got:

Columns, in order. They are the fields of a search result, flattened — so a CSV row and a JSON item carry the same information, with no contact details in either.

Title, Agency, PostedDate, ResponseDeadline, PlaceOfPerformanceState,
PostType, BuyerType, SourceShortLabel, SourceFullLabel, ExternalId,
Description, Link, LinksToListingPageOnly, Tags, ContractRadarPostLink

Dates are ISO 8601 UTC (yyyy-MM-ddTHH:mm:ssZ); a missing value is an empty cell. Tags is flattened to one cell as Key: Value; Key: Value — read the JSON endpoint if you need them structured, since tag values routinely contain commas. ContractRadarPostLink is a link to the contract on ContractRadar, which is worth having because Link points at a portal search page rather than the contract itself when LinksToListingPageOnly is true.

New columns are appended at the end, never inserted, so a script that reads by position keeps working. Prefer reading by header name anyway. The one exception so far: the CoverageType column became BuyerType in the same position, and now holds the posting’s own buyer type (Education, SpecialDistrict and so on) rather than the portal’s level of government.

Errors

If your subscription lapses the token keeps working for search, falling back to the free daily search quota; the CSV export is Pro-only and starts returning 403. Generate, regenerate, or revoke the token from your profile.