Concepts
Pagination and filtering
Every listing answers a page at a time, in one envelope: the rows in
data, the URLs in
links, the numbers in
meta.
Two parameters, one ceiling
page selects the page and per_page its size, up to
100. Ask for more and you get 100; ask for zero and you get one. The
clamping is silent by design, and meta.per_page always states what was actually
used, so read the envelope rather than assuming your request was taken literally.
Follow links.next until it is null instead of computing page numbers; the filters
you sent travel with every link, already encoded.
Filters
Filtering listings state their parameters in the reference beside each endpoint, and the OpenAPI document carries the same list. Two conventions hold throughout: filters narrow and never change shape, and an unknown value is a 422 rather than a silently empty page wherever it could be mistaken for a real answer.
For incremental sync of activity, prefer since on the exposures listings: it
cuts by when we last saw the record move, which is the cursor a nightly job wants.
Worked: the reports listing
A mixed page is the shape test for a consumer: the pending row carries every key the complete row does, with what it has not earned yet as null. Write the parser against this page and no later page surprises it.
List reports
GET /api/v1/reports
The team's reports, newest first.
reports:read paginated
Query parameters
status
enum
Only reports in this state.
address
string
Only reports whose address contains this text.
property
string
Only reports filed under this saved property.
Answers
200
The answer.
Plus the shared refusals: 401, 402, 403, 404, 422 and 429, described on Errors.
curl https://titanweather.com/api/v1/reports \
-H "Authorization: Bearer $TITAN_API_TOKEN"$titan = new \GuzzleHttp\Client([
'base_uri' => 'https://titanweather.com',
'headers' => ['Authorization' => 'Bearer '.getenv('TITAN_API_TOKEN')],
]);
$response = $titan->get('/api/v1/reports');
$reports = json_decode((string) $response->getBody(), true);const response = await fetch('https://titanweather.com/api/v1/reports', {
headers: {
Authorization: `Bearer ${process.env.TITAN_API_TOKEN}`,
},
});
const reports = await response.json();import os
import requests
response = requests.get(
"https://titanweather.com/api/v1/reports",
headers={
"Authorization": f"Bearer {os.environ['TITAN_API_TOKEN']}",
},
)
reports = response.json(){
"data": [
{
"id": "0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
"object": "report",
"status": "complete",
"address": {
"query": "1428 Cedar Ridge Dr, Plano, TX 75023",
"street": "1428 Cedar Ridge Dr",
"city": "Plano",
"state": "TX",
"postal_code": "75023",
"county": "Collin",
"latitude": 33.0412,
"longitude": -96.6996
},
"window": {
"start": "2016-08-23",
"end": "2026-08-23",
"radius_miles": 5,
"narrowed_by_plan": false
},
"property_id": "0198a3f2-6d7e-7b41-92c5-2f6a1c9d4e88",
"event_count": 14,
"observation_count": 41,
"coverage": {
"complete": true,
"provisional": false,
"summary": "All nine sources answered for the full period.",
"sources_searched": [
"noaa_storm_events",
"iem_lsr",
"spc_reports",
"noaa_swdi",
"cocorahs"
]
},
"headline": "Hail to 2.75 in within 1 mile, most recently April 21, 2023.",
"findings": [
{
"family": "hail",
"family_label": "Hail",
"event_count": 9,
"peak_severity": "severe",
"evidence_kinds": [
"ground",
"radar"
],
"evidence_labels": [
"Ground report",
"Radar detection"
],
"dates": [
"2023-04-21",
"2021-04-28",
"2019-06-09"
],
"most_recent": "2023-04-21",
"peak_hail_in": 2.75,
"peak_wind_mph": null,
"peak_tornado_ef": null,
"nearest_miles": 0.8,
"any_observed": true,
"confidence": "high",
"confidence_label": "High confidence",
"statement": "Nine hail events on record, the largest 2.75 in measured 0.8 miles away."
}
],
"failure_reason": null,
"plan_tier": "professional",
"layout": {
"sections": [
"summary",
"findings",
"map",
"events"
],
"imagery": [
"aerial",
"street_view"
],
"elements": [
"key_figures"
],
"map": null
},
"created_at": "2026-08-21T16:44:09Z",
"generated_at": "2026-08-21T16:45:03Z",
"pdf": {
"status": "ready",
"rendered_at": "2026-08-21T16:45:41Z"
},
"links": {
"self": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60",
"events": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/events",
"pdf": "https://titanweather.com/api/v1/reports/0198b6c0-51a9-70f2-8e4d-93b2a7c15f60/pdf"
}
},
{
"id": "0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
"object": "report",
"status": "pending",
"address": {
"query": "1428 Cedar Ridge Dr, Plano, TX 75023",
"street": null,
"city": null,
"state": null,
"postal_code": null,
"county": null,
"latitude": null,
"longitude": null
},
"window": {
"start": "2016-08-23",
"end": "2026-08-23",
"radius_miles": 5,
"narrowed_by_plan": false
},
"property_id": null,
"event_count": 0,
"observation_count": 0,
"coverage": {
"complete": false,
"provisional": false,
"summary": null,
"sources_searched": []
},
"headline": null,
"findings": null,
"failure_reason": null,
"plan_tier": "professional",
"layout": {
"sections": [
"summary",
"findings",
"map",
"events"
],
"imagery": [
"aerial",
"street_view"
],
"elements": [
"key_figures"
],
"map": null
},
"created_at": "2026-08-23T14:02:11Z",
"generated_at": null,
"pdf": {
"status": null,
"rendered_at": null
},
"links": {
"self": "https://titanweather.com/api/v1/reports/0198b6c1-22e4-7f88-a1c9-5d40b7e2913a",
"events": null,
"pdf": null
}
}
],
"links": {
"first": "https://titanweather.com/api/v1/reports?page=1",
"last": "https://titanweather.com/api/v1/reports?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://titanweather.com/api/v1/reports",
"per_page": 25,
"to": 2,
"total": 2
}
}