webread — Read web content over HTTP/HTTPS and decode responses with MATLAB-compatible behavior.
webread issues HTTP/HTTPS requests and returns decoded response content (text, JSON, or bytes) using MATLAB-compatible weboptions and query-parameter workflows.
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.
- Optional
weboptions-style fields (either through a struct argument or name-value pairs) control content decoding (ContentType), request timeout (Timeout), headers (HeaderFields), and authentication (Username/Password). The builtin currently supports the defaultGETrequest method; usewebwritefor POST/PUT uploads. - Additional name-value pairs that do not match an option are appended to the query string using percent-encoding. A leading struct or cell array argument can also supply query parameters.
ContentType 'auto'(default) inspects theContent-Typeresponse header to choose between JSON, text, or binary decoding. ExplicitContentType '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 preserve the server-provided character encoding (UTF-8 with automatic decoding of exotic charsets exposed in the HTTP headers). Binary payloads return
1×Ndouble arrays whose entries store byte values in the range 0–255. - HTTP errors (non-2xx status codes), timeouts, TLS failures, and parsing problems raise descriptive MATLAB-style errors.
Does RunMat run webread on the GPU?
webread runs entirely on the CPU. Any gpuArray inputs (for example, query parameter values) are gathered to host memory before building the HTTP request. Results are produced on the host, and fusion graphs terminate at this builtin via ResidencyPolicy::GatherImmediately.
GPU memory and residency
No. webread gathers any GPU-resident values before contacting the network and produces host results. Keeping inputs on the GPU offers no benefit because HTTP/TLS stacks operate on the CPU.
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.3Downloading 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?⌄
Supply "Timeout", seconds as a name-value pair or in an options struct. The default timeout is 60 seconds. Timeouts raise webread: request to <url> timed out.
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 1×N double arrays whose elements are byte values. Convert them to the desired integer type (for example uint8) before further processing.
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?⌄
Yes. Inputs wrapped in gpuArray are gathered before assembling the query string.
Related Io functions
Http
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · savepath · setenv · tempdir · tempname
Tabular
csvread · csvwrite · dlmread · dlmwrite · readmatrix · writematrix
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Json
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.