`webread` — Read and decode content from a web service.

webread issues an HTTP or HTTPS GET request and decodes the response according to its content type and options.

Syntax

data = webread(url)
data = webread(url, optionsStruct)
data = webread(url, queryParameters)
data = webread(url, name, value, ...)
data = webread(url, optionsStruct, name, value, ...)
data = webread(url, queryParameters, name, value, ...)

Inputs

Name	Type	Required	Default	Description
`url`	`StringScalar`	Yes	—	HTTP/HTTPS URL to fetch.
`optionsStruct`	`Any`	Yes	—	weboptions struct or option struct literal.
`queryParameters`	`Any`	Yes	—	Two-column cell array of query parameter names and values.
`name`	`StringScalar`	Variadic	—	Option or query parameter name.
`value`	`Any`	Variadic	—	Option or query parameter value.

Returns

Name	Type	Description
`data`	`Any`	Downloaded payload decoded as JSON, text, or binary tensor.

Errors

Identifier	When	Message
`RunMat:webread:InvalidArgument`	Argument type/shape does not match webread call contract.	`webread: invalid argument`
`RunMat:webread:InvalidUrl`	URL input is empty or invalid.	`webread: invalid URL`
`RunMat:webread:MissingOptionValue`	A name-value key has no corresponding value.	`webread: missing option value`
`RunMat:webread:InvalidOptionValue`	An option value fails validation.	`webread: invalid option value`
`RunMat:webread:InvalidCredentials`	Password is provided without username.	`webread: invalid credentials`
`RunMat:webread:Transport`	HTTP transport fails.	`webread: transport failure`
`RunMat:webread:ResponseJson`	Response body cannot be decoded as JSON.	`webread: failed to parse JSON response`
`RunMat:webread:Output`	Output payload cannot be materialized.	`webread: output materialization failure`
`RunMat:webread:Flow`	Nested flow fails while gathering inputs.	`webread: flow failure`

How `webread` works

Accepts URLs supplied as character vectors or string scalars; the URL must be absolute.
Query names are text. Query values may be text, numeric, or logical scalars or vectors; native integer values are formatted from exact storage without conversion to double. Vector values use comma-separated formatting in the current implementation.
A final options structure controls response decoding (ContentType), timeout (Timeout), headers (HeaderFields), and authentication (Username and Password). The default timeout is 5 seconds, and an integer timeout is read exactly.
RunMat also accepts a leading structure or cell array of query parameters and recognizes option-like direct name-value pairs. These conveniences do not replace the portable query-pair plus final-options form.
ContentType 'auto' (default) inspects the Content-Type response header to choose between JSON, text, or binary decoding. Explicit ContentType 'json', 'text', or 'binary' override the detection logic.
JSON responses are parsed with the same rules as jsondecode, producing doubles, logicals, strings, structs, and cell arrays that match MATLAB semantics.
Text responses use the response character encoding when supported. Binary payloads return an exact 1×N uint8 row vector.
Image, audio, table, XML DOM, raw-response, and custom ContentReader result forms are not yet implemented.
HTTP errors (non-2xx status codes), timeouts, TLS failures, and parsing problems raise descriptive MATLAB-style errors.

Does RunMat run `webread` on the GPU?

The request path terminates fusion and gathers automatically resident values through their owning provider. Explicit gpuArray input crosses the webread-explicit-gpu-input extension gate before any gather.

GPU memory and residency

HTTP and TLS execute on the host and results are host-resident. Automatically resident values gather transparently; explicit gpuArray input requires RunMat mode.

Examples

Reading JSON data from a REST API

opts = weboptions("ContentType", "json", "Timeout", 15);
weather = webread("https://api.example.com/weather", opts, "city", "Reykjavik");
disp(weather.temperatureC)

Expected output:

2.3

Downloading plain text as a character vector

html = webread("https://example.com/index.txt", "Timeout", 5);
extract = html(1:200)

Retrieving binary payloads such as images

bytes = webread("https://example.com/logo.png", "ContentType", "binary");
filewrite("logo.png", uint8(bytes))

Supplying custom headers and credentials

headers = struct("Accept", "application/json", "X-Client", "RunMat");
data = webread("https://api.example.com/me", ...
               "Username", "ada", "Password", "secret", ...
               "HeaderFields", headers, ...
               "ContentType", "json")

Passing query parameters as a struct

query = struct("limit", 25, "sort", "name");
response = webread("https://api.example.com/resources", query, "ContentType", "json")

Using `webread` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how webread changes the result.

Run a small webread example, explain the result, then change one input and compare the output.

FAQ

Can webread decode JSON automatically?⌄

Yes. When the server reports a JSON Content-Type header (for example application/json or application/vnd.api+json) the builtin decodes it using the same rules as jsondecode. Override the behaviour with "ContentType","text" or "ContentType","binary" when needed.

How do I control request timeouts?⌄

Set Timeout in a final options structure. The default is 5 seconds; a positive scalar up to 2147.483647 seconds or Inf is accepted.

What headers can I set?⌄

Use "HeaderFields", struct(...) or a cell array of name/value pairs. Header names must be valid HTTP tokens. The builtin automatically sets a RunMat-specific User-Agent string unless you override it with "UserAgent", "..."

Does webread follow redirects?⌄

Yes. The underlying HTTP client follows redirects up to the platform default limit while preserving headers and authentication.

How do I provide credentials?⌄

Use "Username", "user", "Password", "pass" for HTTP basic authentication. Supplying a password without a username raises an error.

Can I send POST or PUT requests?⌄

webread is designed for read-only requests and currently supports the default GET method. Use webwrite (planned) for requests that include bodies or mutate server state.

How are binary responses represented?⌄

Binary payloads return an exact 1×N uint8 row vector.

What happens when the server returns an error status?⌄

Non-success HTTP status codes raise webread: request to … failed with HTTP status XYZ. Inspect the remote server logs or response headers for additional diagnostics.

Does webread support compressed responses?⌄

Yes. The builtin enables gzip / deflate content decoding through the HTTP client automatically.

Can I pass query parameters as GPU arrays?⌄

Automatically resident query values gather transparently. Explicit gpuArray query values are supported only in RunMat mode and are rejected before provider access in MATLAB-compatible mode.

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how webread is executed, line by line, in Rust.

View the source for webread in Rust on GitHub
Learn how the RunMat runtime works
Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

`webread` — Read and decode content from a web service.

webread issues an HTTP or HTTPS GET request and decodes the response according to its content type and options.

Syntax

data = webread(url)
data = webread(url, optionsStruct)
data = webread(url, queryParameters)
data = webread(url, name, value, ...)
data = webread(url, optionsStruct, name, value, ...)
data = webread(url, queryParameters, name, value, ...)

Inputs

Name	Type	Required	Default	Description
`url`	`StringScalar`	Yes	—	HTTP/HTTPS URL to fetch.
`optionsStruct`	`Any`	Yes	—	weboptions struct or option struct literal.
`queryParameters`	`Any`	Yes	—	Two-column cell array of query parameter names and values.
`name`	`StringScalar`	Variadic	—	Option or query parameter name.
`value`	`Any`	Variadic	—	Option or query parameter value.

Returns

Name	Type	Description
`data`	`Any`	Downloaded payload decoded as JSON, text, or binary tensor.

Errors

Identifier	When	Message
`RunMat:webread:InvalidArgument`	Argument type/shape does not match webread call contract.	`webread: invalid argument`
`RunMat:webread:InvalidUrl`	URL input is empty or invalid.	`webread: invalid URL`
`RunMat:webread:MissingOptionValue`	A name-value key has no corresponding value.	`webread: missing option value`
`RunMat:webread:InvalidOptionValue`	An option value fails validation.	`webread: invalid option value`
`RunMat:webread:InvalidCredentials`	Password is provided without username.	`webread: invalid credentials`
`RunMat:webread:Transport`	HTTP transport fails.	`webread: transport failure`
`RunMat:webread:ResponseJson`	Response body cannot be decoded as JSON.	`webread: failed to parse JSON response`
`RunMat:webread:Output`	Output payload cannot be materialized.	`webread: output materialization failure`
`RunMat:webread:Flow`	Nested flow fails while gathering inputs.	`webread: flow failure`

How `webread` works

Accepts URLs supplied as character vectors or string scalars; the URL must be absolute.
Query names are text. Query values may be text, numeric, or logical scalars or vectors; native integer values are formatted from exact storage without conversion to double. Vector values use comma-separated formatting in the current implementation.
A final options structure controls response decoding (ContentType), timeout (Timeout), headers (HeaderFields), and authentication (Username and Password). The default timeout is 5 seconds, and an integer timeout is read exactly.
RunMat also accepts a leading structure or cell array of query parameters and recognizes option-like direct name-value pairs. These conveniences do not replace the portable query-pair plus final-options form.
ContentType 'auto' (default) inspects the Content-Type response header to choose between JSON, text, or binary decoding. Explicit ContentType 'json', 'text', or 'binary' override the detection logic.
JSON responses are parsed with the same rules as jsondecode, producing doubles, logicals, strings, structs, and cell arrays that match MATLAB semantics.
Text responses use the response character encoding when supported. Binary payloads return an exact 1×N uint8 row vector.
Image, audio, table, XML DOM, raw-response, and custom ContentReader result forms are not yet implemented.
HTTP errors (non-2xx status codes), timeouts, TLS failures, and parsing problems raise descriptive MATLAB-style errors.

Does RunMat run `webread` on the GPU?

GPU memory and residency

HTTP and TLS execute on the host and results are host-resident. Automatically resident values gather transparently; explicit gpuArray input requires RunMat mode.

Examples

Reading JSON data from a REST API

opts = weboptions("ContentType", "json", "Timeout", 15);
weather = webread("https://api.example.com/weather", opts, "city", "Reykjavik");
disp(weather.temperatureC)

Expected output:

2.3

Downloading plain text as a character vector

html = webread("https://example.com/index.txt", "Timeout", 5);
extract = html(1:200)

Retrieving binary payloads such as images

bytes = webread("https://example.com/logo.png", "ContentType", "binary");
filewrite("logo.png", uint8(bytes))

Supplying custom headers and credentials

headers = struct("Accept", "application/json", "X-Client", "RunMat");
data = webread("https://api.example.com/me", ...
               "Username", "ada", "Password", "secret", ...
               "HeaderFields", headers, ...
               "ContentType", "json")

Passing query parameters as a struct

query = struct("limit", 25, "sort", "name");
response = webread("https://api.example.com/resources", query, "ContentType", "json")

Using `webread` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how webread changes the result.

Run a small webread example, explain the result, then change one input and compare the output.

FAQ

Can webread decode JSON automatically?⌄

How do I control request timeouts?⌄

Set Timeout in a final options structure. The default is 5 seconds; a positive scalar up to 2147.483647 seconds or Inf is accepted.

What headers can I set?⌄

Does webread follow redirects?⌄

Yes. The underlying HTTP client follows redirects up to the platform default limit while preserving headers and authentication.

How do I provide credentials?⌄

Use "Username", "user", "Password", "pass" for HTTP basic authentication. Supplying a password without a username raises an error.

Can I send POST or PUT requests?⌄

webread is designed for read-only requests and currently supports the default GET method. Use webwrite (planned) for requests that include bodies or mutate server state.

How are binary responses represented?⌄

Binary payloads return an exact 1×N uint8 row vector.

What happens when the server returns an error status?⌄

Non-success HTTP status codes raise webread: request to … failed with HTTP status XYZ. Inspect the remote server logs or response headers for additional diagnostics.

Does webread support compressed responses?⌄

Yes. The builtin enables gzip / deflate content decoding through the HTTP client automatically.

Can I pass query parameters as GPU arrays?⌄

Automatically resident query values gather transparently. Explicit gpuArray query values are supported only in RunMat mode and are rejected before provider access in MATLAB-compatible mode.

Http

sendmail · urldecode · urlencode · weboptions · websave · webwrite

Net

accept · read · readline · tcpclient · tcpserver · write

Repl Fs

Tabular

Audio

audioinfo · audioread

Io

clc · diary · disp · display · format · input

Filetext

fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines

Hdf5

h5disp · h5info · h5read · h5write · h5writeatt · hdf5info · hdf5read · hdf5write

Import

importdata · textscan

Json

jsondecode · jsonencode

Mat

load · matfile · save

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how webread is executed, line by line, in Rust.

View the source for webread in Rust on GitHub
Learn how the RunMat runtime works
Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

webread — Read and decode content from a web service.

Syntax

Inputs

Returns

Errors

How webread works

Does RunMat run webread on the GPU?

GPU memory and residency

Examples

Reading JSON data from a REST API

Downloading plain text as a character vector

Retrieving binary payloads such as images

Supplying custom headers and credentials

Passing query parameters as a struct

Using webread with coding agents

FAQ

Related Io functions

Http

Net

Repl Fs

Tabular

Audio

Io

Filetext

Archive

Hdf5

Import

Json

Mat

Open-source implementation

About RunMat

Download RunMat

webread — Read and decode content from a web service.

Syntax

Inputs

Returns

Errors

How webread works

Does RunMat run webread on the GPU?

GPU memory and residency

Examples

Reading JSON data from a REST API

Downloading plain text as a character vector

Retrieving binary payloads such as images

Supplying custom headers and credentials

Passing query parameters as a struct

Using webread with coding agents

FAQ

Related Io functions

Http

Net

Repl Fs

Tabular

Audio

Io

Filetext

Archive

Hdf5

Import

Json

Mat

Open-source implementation

About RunMat

Download RunMat

`webread` — Read and decode content from a web service.

How `webread` works

Does RunMat run `webread` on the GPU?

Using `webread` with coding agents

`webread` — Read and decode content from a web service.

How `webread` works

Does RunMat run `webread` on the GPU?

Using `webread` with coding agents