The Trawley API is a small, read-oriented HTTP API for querying the data your scrapers collect. If you can make an HTTP request, you can use it. No SDK required.
Base URL
https://api.trawley.ai
Every endpoint is scoped to a single scraper:
/v1/scrapers/{scraperId}/...
Your scraperId is the last segment of the scraper's dashboard URL
(for example scr_8f2a1c9e).
Conventions
- Requests are HTTP
GETunless noted, with parameters in the query string. - Responses are JSON.
- Search-style endpoints share a common envelope: a
dataarray, apaginationobject, and ametaobject.
{
"data": [ /* records */ ],
"pagination": { "total": 0, "page": 1, "take": 10, "totalPages": 0, "hasMore": false },
"meta": { /* endpoint-specific */ }
}
Authentication
There is no API key yet. Endpoints are currently reached by scraper ID, and a scraper's results are returned to anyone who has its ID. Authentication and per-key access control are on the roadmap.
What this means in practice today:
- Treat a
scraperIdlike a shared secret. Anyone with it can read that scraper's results. - Do not embed scraper IDs in public client-side code you would not want copied.
- When authentication ships, existing endpoints keep working and gain an
Authorizationheader. We will document the migration here.
Rate limits
Search API calls are metered against your team's plan. When you exceed your
monthly allowance the API responds with 429 Too Many Requests. Upgrade your
plan or wait for the next billing period to reset. See
billing and plans for current limits.
Endpoints at a glance
| Endpoint | Purpose |
|---|---|
GET /v1/scrapers/{id}/hybrid | Natural language search (recommended) |
GET /v1/scrapers/{id}/results | Raw paginated results, no query |
GET /v1/scrapers/{id}/export | Bulk export of all results |
GET /v1/scrapers/{id}/diff | Differences between scrape runs |
POST /v1/scrapers/{id}/chat | Conversational queries over results |