AgentQL REST API reference
AgentQL's REST API allows you to query web pages and documents like PDFs and image files to retrieve the results through HTTP requests from any language.
Query data
Queries structured data as JSON from a web page given a URL using either an AgentQL query.
curl -X POST https://api.agentql.com/v1/query-data \
-H "X-API-Key: $AGENTQL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "{ products[] { product_name product_price(integer) } }",
"url": "https://scrapeme.live/?s=fish&post_type=product",
"params": {
"wait_for": 0,
"is_scroll_to_bottom_enabled": false,
"mode": "fast",
"is_screenshot_enabled": false
}
}'
Make sure to replace $AGENTQL_API_KEY
with your actual API key.
{
"data": {
"products": [
{
"product_name": "Qwilfish",
"price": 77
},
{
"product_name": "Huntail",
"price": 52
},
...
]
},
"metadata": {
"request_id": "ecab9d2c-0212-4b70-a5bc-0c821fb30ae3"
}
}
Authentication
All requests to the AgentQL API must include an X-API-Key
header with your API key.
You can generate an API key through Dev Portal.
Request body for web queries
-
query
string (alternative toprompt
)The AgentQL query to execute. Learn more about how to write an AgentQL query in the docs. Note: You must define either a
query
or aprompt
to use AgentQL. -
prompt
string (alternative toquery
)A Natural Language description of the data to query the page for. AgentQL infers the data structure from your prompt. Note: You must define either a
query
or aprompt
to use AgentQL. -
url
string (alternative tohtml
)The URL of the public web page you want to query. Note: You must define either a
url
orhtml
to use AgentQL. -
html
string (alternative tourl
)The raw HTML to query data from. Useful if you have a private or locally generated copy of a web page. Note: You must define either a
url
orhtml
to use AgentQL. -
params
object (optional)-
wait_for
numberThe number of seconds to wait for the page to load before querying. Defaults to
0
. -
is_scroll_to_bottom_enabled
booleanWhether to scroll to bottom of the page before querying. Defaults to
false
. -
mode
strstandard
uses deep data analysis, whilefast
trades some depth of analysis for speed and is adequate for most usecases. Learn more about the modes in this guide. Defaults tofast
. -
is_screenshot_enabled
booleanWhether to take a screenshot before extracting data. Returned in
metadata
as a Base64 string. Defaults tofalse
.
-
Response for web queries
-
data
objectData that matches the query.
-
metadata
object-
request_id
stringA Universally Unique Identifier (UUID) for the request.
-
screenshot
string | nullBase64 encoded screenshot if enabled,
null
otherwise. You can convert the Base64 string returned in thescreenshot
field to an image and view it using free online tools like Base64.guru.
-
Query document
Extract data from a webpage by sending a PDF or image (JPEG, JPG, PNG) file and an AgentQL query. Learn about the consumption logic for querying documents here
for this example, use the following example file
The query_document
function consumes 1 API call per image (JPG, JPEG, JPG), and 1 API call for each page within a PDF. (i.e querying a 10-page PDF will take 10 AgentQL API calls)
curl -X POST https://api.agentql.com/v1/query-document \
-H "X-API-Key: $AGENTQL_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "file=@/path/to/file.pdf" \
-F 'body="{\"query\": \"{ project { id lowest_bidder lowest_bid } } \", \"params\": { \"mode\": \"fast\" } }" '
Make sure to replace $AGENTQL_API_KEY
with your actual API key.
{
"data": {
"project": {
"id": "CPM 81031-200202",
"lowest_bidder": "Toebe Construction LLC",
"lowest_bid": 13309641.63
}
},
"metadata": {
"request_id": "ecab9d2c-0212-4b70-a5bc-0c821fb30ae3"
}
}
Authentication
All requests to the AgentQL API must include an X-API-Key
header with your API key.
You can generate an API key through Dev Portal.
Request body for document queries
The request body for querying documents is a multipart/form-data object that contains a file and a body.
-
file
stringFile Path of file to execute query on.
-
body
stringThe body is a stringified JSON that represents parameters for the query because multipart/form-data only takes string.
query
string (alternative toprompt
):
The AgentQL query to execute. Learn more about how to write an AgentQL query in the docs. Note: You must define either a
query
or aprompt
to use AgentQL.prompt
string (alternative toquery
):
A Natural Language description of the data to query the page for. AgentQL infers the data structure from your prompt. Note: You must define either a
query
or aprompt
to use AgentQL.params
object (optional):
representation of the parameters for the query.
mode
str: Specifies the extraction mode:standard
for complex or high-volume data, orfast
for typical use cases. Defaults tofast
.
Response for document queries
-
data
objectData that matches the query
-
metadata
object-
request_id
stringA UUID for the request
-
The query_document
is supported in Python SDK. Learn how to use it here