> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/concepts/api-calls.md). # API Calls How requests and responses work across the Vulcan API. ## Base URL Every data product is accessible at a unique URL constructed from your environment variables: ``` https:///vulcan/tenants//data-products/-/api/v1 ``` ## HTTP Methods

Method	What it does
`GET`	Retrieve a resource or list
`POST`	Create a resource or submit a query
`PUT`	Update an existing resource
`DELETE`	Remove a resource
`HEAD`	Check existence without fetching the body

## Responses All responses are JSON unless the endpoint explicitly returns binary (e.g. Parquet export). Standard status codes:

Code	Meaning
`200`	Success — body contains the result
`201`	Created — new resource successfully made
`202`	Accepted — request received, processing async (query submissions)
`204`	No Content — success with no body (e.g. DELETE)
`307`	Redirect — follow to presigned URL (Parquet downloads)
`400`	Bad Request — invalid SQL, bad params, missing required field
`401`	Unauthorized — token missing or expired
`403`	Forbidden — you don't own this resource
`404`	Not Found — resource doesn't exist
`409`	Conflict — e.g. perspective slug already taken
`502`	Upstream Error — transpiler or proxy failure
`503`	Service Unavailable — worker not ready, retry shortly

## Pagination List endpoints accept `limit` and `offset` query parameters. Responses include a `pagination` object with `has_more`, `limit`, and `offset` fields. ``` GET /api/v1/activity/runs?limit=20&offset=40 # Returns runs 41–60. Check pagination.has_more to continue paging. ``` ## Timestamps All timestamps in responses are Unix epoch seconds (`integer`) unless noted as ISO 8601. When filtering by time, pass Unix seconds in `start_ts` / `end_ts` query parameters. ## Async Query Pattern Data query endpoints are asynchronous. All `POST /query/...` calls return `202 Accepted` immediately with a `statement_id`. Poll `GET /query/statement/{id}` until `status` is `SUCCESS` or `FAILED`, then fetch the result. > **Cache deduplication:** Identical queries are fingerprinted. If the same query is already running or cached, the API returns the existing result. Check the `strategy` field: `from_cache`, `await_primary`, or `execute`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/references/interfaces/apis/concepts/api-calls.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.