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
    }
  }'

{
  "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

  The AgentQL query to execute. Learn more about how to write an AgentQL query in the docs.

• url string (optional)

  The URL of the public web page you want to query. Note: You must define either a url or html to use AgentQL.

• html string (optional)

  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 or html to use AgentQL.

• params object (optional)

  • wait_for number

    The number of seconds to wait for the page to load before querying. Defaults to 0.

  • is_scroll_to_bottom_enabled boolean

    Whether to scroll to bottom of the page before querying. Defaults to false.

  • mode str

    standard uses deep data analysis, while fast trades some depth of analysis for speed and is adequate for most usecases. Learn more about the modes in this guide. Defaults to fast.

  • is_screenshot_enabled boolean

    Whether to take a screenshot before extracting data. Returned in metadata as a Base64 string. Defaults to false.

Response for web queries

• data object

  Data that matches the query.

• metadata object

  • request_id string

    A Universally Unique Identifier (UUID) for the request.

  • screenshot string | null

    Base64 encoded screenshot if enabled, null otherwise. You can convert the Base64 string returned in the screenshot 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 (jpg, jpeg, png) file and an AgentQL query.

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 "query= { students[] { name role } } " \
    -F "params= { \"mode\": \"fast\" }"

{
  "data": {
    "students": [
      {
        "name": "Qwilfish",
        "role": "chairman"
      },
      {
        "name": "Huntail",
        "role": "vice chairman"
      },
      ...
    ]
  },
  "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

• query string

  The AgentQL query to execute. Alternatively, you can use the prompt field to describe the query.

• prompt string

  Natural language description of what you want to extract from the file. It will convert the prompt into an AgentQL query and execute it.

• file path

  Buffered Object representation of the file to extract data from

• params object (optional)

  • mode str

    Specifies the extraction mode: standard for complex or high-volume data, or fast for typical use cases. Defaults to fast. You can read more about the mode options in Guide. Only configurable in curl requests.

Response for document queries

• data object

  Data that matches the query

• metadata object

  • request_id string

    A UUID for the request