URL

Fetch a remote file by URL and parse it into the { columns, rows } Data structure used by Graphy agents and chart configs. The format is auto-detected from the URL path extension.

fromURL

import { fromURL } from '@graphysdk/data-import-utils/url';

const data = await fromURL('https://example.com/sales.csv');
const data = await fromURL('https://example.com/report.xlsx', { sheet: 'Revenue' });

Signature

function fromURL(
  url: string,
  options?: URLParseOptions
): Promise<Data>

Options

string

required

URL to fetch. The path extension determines the format, falling back to the response Content-Type header.

Record<string, string>

Custom headers to include in the fetch request. Useful for authenticated endpoints (e.g. { Authorization: 'Bearer token' }).

number

default:"30000"

Fetch timeout in milliseconds. The request is aborted if it takes longer.

AbortSignal

Optional external abort signal for cancellation. Combined with the internal timeout signal via AbortSignal.any.

boolean

default:"true"

Whether the first row contains column headers (CSV/TSV only). When false, columns are auto-named Column 1, Column 2, etc.

string | number

default:"0"

Sheet to parse (spreadsheets only). Pass a sheet name or 0-based index.

VizLocale

default:"EN_US"

Locale for number parsing. Determines thousand/decimal separator conventions.

number

default:"5"

Maximum allowed input size in megabytes. The response body is streamed with a byte budget — the download is aborted early if the limit is exceeded.

number

default:"100000"

Maximum number of data rows to process (spreadsheets only).

number

default:"5000000"

Maximum total cells to process (spreadsheets only).

Supported Extensions

Extension	Format
`.csv`	CSV
`.tsv`, `.tab`	TSV
`.xlsx`	XLSX
`.xls`	XLS
`.ods`	ODS

Unsupported extensions throw an error listing the supported formats.

Examples

With the AI SDK

import { fromURL } from '@graphysdk/data-import-utils/url';
import { GraphyAiSdk } from '@graphysdk/agents-sdk';

const ai = new GraphyAiSdk({
  apiKey: process.env.GRAPHY_API_KEY,
  baseUrl: 'https://agents.graphy.dev',
});

const data = await fromURL('https://data.example.com/quarterly-sales.csv');

const result = await ai.generateGraph({
  config: { data },
  userPrompt: 'line chart showing quarterly trends',
});

Error Handling

try {
  const data = await fromURL('https://example.com/data.pdf');
} catch (error) {
  // Error: Unsupported file extension ".pdf". Supported: .csv, .tsv, .tab, .xlsx, .xls, .ods
}

With Custom Headers

const data = await fromURL('https://api.example.com/data.csv', {
  headers: { Authorization: 'Bearer my-token' },
});

With Timeout and Cancellation

const controller = new AbortController();

const data = await fromURL('https://example.com/large-file.xlsx', {
  timeout: 10_000,
  signal: controller.signal,
});

SSRF Protection: fromURL validates URLs before fetching. Private and reserved IP addresses (e.g. 127.0.0.1, 10.x.x.x, 192.168.x.x, 169.254.x.x, localhost, IPv6 loopback/link-local) are blocked, and only http: and https: schemes are allowed. This prevents server-side request forgery when URLs are provided by end users.

fromURL uses the global fetch API and works in Node.js 18+ and all modern browsers. For authenticated endpoints, you can either pass headers in the options or fetch the data yourself and use the format-specific parsers (fromCSV, fromXLSX, etc.) directly.

Get Started

Sources

Formats

fromURL

Signature

Options

Supported Extensions

Examples

With the AI SDK

Error Handling

With Custom Headers

With Timeout and Cancellation

​fromURL

​Signature

​Options

​Supported Extensions

​Examples

​With the AI SDK

​Error Handling

​With Custom Headers

​With Timeout and Cancellation

fromURL

Signature

Options

Supported Extensions

Examples

With the AI SDK

Error Handling

With Custom Headers

With Timeout and Cancellation