Search observations
curl --request POST \
--url https://app.jolts.xyz/api/observations/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"query": "charging",
"filters": {
"countries": [
"CA"
]
},
"limit": 10
}
'import requests
url = "https://app.jolts.xyz/api/observations/search"
payload = {
"query": "charging",
"filters": { "countries": ["CA"] },
"limit": 10
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({query: 'charging', filters: {countries: ['CA']}, limit: 10})
};
fetch('https://app.jolts.xyz/api/observations/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));require 'uri'
require 'net/http'
url = URI("https://app.jolts.xyz/api/observations/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"charging\",\n \"filters\": {\n \"countries\": [\n \"CA\"\n ]\n },\n \"limit\": 10\n}"
response = http.request(request)
puts response.read_body{
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
},
"coverage_status": "partial",
"retrieval": "lexical",
"as_of": "2023-11-07T05:31:56Z",
"next_cursor": "<string>",
"withheld_units": 1,
"delivery_unit": "company",
"observations": [
{
"id": 2,
"kind": "procurement_request",
"observed_fact": "<string>",
"why_it_may_matter": "<string>",
"demand_class": "explicit_request",
"country": "CA",
"confidence": 0.5,
"occurred_at": "2023-11-07T05:31:56Z",
"observed_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"evidence": [
{
"source_uri": "<string>",
"excerpt": "<string>",
"occurred_at": "2023-11-07T05:31:56Z",
"observed_at": "2023-11-07T05:31:56Z"
}
],
"company": {
"id": 2,
"name": "<string>"
}
}
]
}{
"usage": {
"id": 789,
"status": "pending",
"request_key": "first-company-search",
"request_units": 0,
"delivered_units": 0,
"fresh_evidence_units": 0
},
"request_allowance": {
"window_seconds": 18000,
"window_remaining": 99,
"weekly_remaining": 499
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}Observations
Search observations
Find individual evidence-backed company activities using a literal query and exact filters. Unlike company search, this endpoint does not interpret the query through company-search planning or group results by company. Use short relevant terms, such as charging. Results are newest-observed first.
Country, kind, demand-class and timestamp filters are supported. Company ID lists, domain lists and background are not accepted. To queue this search, use POST /api/usages. Read the evidence guide before treating an observation as buying intent.
POST
/
api
/
observations
/
search
Search observations
curl --request POST \
--url https://app.jolts.xyz/api/observations/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"query": "charging",
"filters": {
"countries": [
"CA"
]
},
"limit": 10
}
'import requests
url = "https://app.jolts.xyz/api/observations/search"
payload = {
"query": "charging",
"filters": { "countries": ["CA"] },
"limit": 10
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({query: 'charging', filters: {countries: ['CA']}, limit: 10})
};
fetch('https://app.jolts.xyz/api/observations/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));require 'uri'
require 'net/http'
url = URI("https://app.jolts.xyz/api/observations/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"charging\",\n \"filters\": {\n \"countries\": [\n \"CA\"\n ]\n },\n \"limit\": 10\n}"
response = http.request(request)
puts response.read_body{
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
},
"coverage_status": "partial",
"retrieval": "lexical",
"as_of": "2023-11-07T05:31:56Z",
"next_cursor": "<string>",
"withheld_units": 1,
"delivery_unit": "company",
"observations": [
{
"id": 2,
"kind": "procurement_request",
"observed_fact": "<string>",
"why_it_may_matter": "<string>",
"demand_class": "explicit_request",
"country": "CA",
"confidence": 0.5,
"occurred_at": "2023-11-07T05:31:56Z",
"observed_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"evidence": [
{
"source_uri": "<string>",
"excerpt": "<string>",
"occurred_at": "2023-11-07T05:31:56Z",
"observed_at": "2023-11-07T05:31:56Z"
}
],
"company": {
"id": 2,
"name": "<string>"
}
}
]
}{
"usage": {
"id": 789,
"status": "pending",
"request_key": "first-company-search",
"request_units": 0,
"delivered_units": 0,
"fresh_evidence_units": 0
},
"request_allowance": {
"window_seconds": 18000,
"window_remaining": 99,
"weekly_remaining": 499
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"retry_at": "2023-11-07T05:31:56Z",
"retry_after_seconds": 1
},
"usage": {
"id": 2,
"status": "pending",
"request_key": "<string>",
"request_units": 1,
"delivered_units": 1,
"fresh_evidence_units": 1
},
"request_allowance": {
"window_seconds": 1,
"window_remaining": 1,
"weekly_remaining": 1
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Unique operation key. Reuse only for identical retries, including across HTTP/MCP. Each new page needs a new key.
Body
application/json
Required string length:
1 - 500Show child attributes
Show child attributes
Maximum page size is subscription-owned: builder 25, professional 50.
Required range:
x >= 1Opaque cursor. Keep query, filters and limit unchanged; use a new request key for each page.
Response
Current observation page.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Allowed value:
"partial"Available options:
lexical, hybrid Required range:
x >= 0Available options:
company, observation Show child attributes
Show child attributes