How to Call a Web Page with UTL_HTTP.REQUEST

UTL_HTTP.REQUEST is the shortest way to call a web service from the database: one function call that sends a GET request and returns the response body. It works in SQL too, so a JSON response can be read with JSON_VALUE in the same query.

Code for This Guide

The main examples are in the examples/pkg-files-network folder of the Oracle Database 26ai code repository on GitHub, each with its output. They use NIMBUS, the sample schema of a fictional airline, which you can install with the scripts in the setup/nimbus folder.

They come from Oracle Database 26ai SQL and PL/SQL Book.

Syntax

utl_http.request(url [, proxy] [, wallet_path, wallet_password]) return varchar2

It returns up to the first 2,000 bytes of the response. The host and port need an access control entry with the http privilege.

The examples call a small local test server, setup/netlab/server.mjs in the repository, started with node setup/netlab/server.mjs on the machine that runs the database container.

Call a Service in SQL

Example:

select utl_http.request('http://host.docker.internal:8099/flights/NM150/status')
       as response;

select json_value(utl_http.request('http://host.docker.internal:8099/fx?base=USD'),
                  '$.rates.AED') as usd_to_aed;

Output:

RESPONSE
___________________________________________________________________________________________
{"flight":"NM150","status":"ON TIME","gate":"B12","departs":"2026-03-15T22:10:00+13:00"}

USD_TO_AED
_____________
3.6725

The first query returns the flight status JSON as it came. The second calls an exchange rate service and reads one rate with JSON_VALUE: one US dollar is 3.6725 dirhams.

Error Responses

Example:

-- an unknown path: REQUEST returns the error body, not an error
select utl_http.request('http://host.docker.internal:8099/no/such/path') as response;

Output:

RESPONSE
________________________
{"error":"not found"}

The path does not exist, and the server answers with status 404, but REQUEST does not fail: it returns the error body. REQUEST cannot show the status code, so use BEGIN_REQUEST and GET_RESPONSE when the status matters.

Things to Know

• REQUEST returns at most 2,000 bytes; REQUEST_PIECES returns longer responses in 2,000-byte pieces.
• Escape values placed in the URL with UTL_URL.ESCAPE.
• Network calls are slow compared with SQL; avoid them for every row of a large query.

Related Guides

• How to Encode URLs with UTL_URL
• How to Allow Network Access with DBMS_NETWORK_ACL_ADMIN

Conclusion

UTL_HTTP.REQUEST sends a GET request and returns the response body in one call, from SQL or PL/SQL. Use it for short responses where the status code does not matter, and the full request API otherwise.