@outputai/http

Make traceable HTTP requests from your steps

The @outputai/http package gives you an HTTP client that automatically shows up in your traces. Every request — URL, method, status code, timing — is recorded as a child node in the trace tree, so you can see exactly what API calls your steps made and how long they took.

Under the hood, it wraps ky, a lightweight HTTP client built on fetch.

Creating a Client

The typical pattern is to create a client per external service in your clients directory, then import it in your steps:

clients/jina.ts

import { httpClient } from '@outputai/http';

export const jina = httpClient({
  prefixUrl: 'https://r.jina.ai',
  headers: {
    'Authorization': `Bearer ${process.env.JINA_API_KEY}`,
    'Accept': 'application/json'
  },
  timeout: 30000
});

You can extend clients to create specialized instances:

const authenticatedClient = jina.extend({
  headers: { 'X-Custom-Header': 'value' }
});

HTTP Methods

// GET
const response = await client.get('https://acme.com');
const data = await response.json();

// POST
const response = await client.post('companies', {
  json: { url: 'https://acme.com' }
});
const result = await response.json();

// PUT
await client.put('companies/123', {
  json: { industry: 'SaaS' }
});

// DELETE
await client.delete('companies/123');

Using in Steps

Wrap HTTP calls in steps for automatic retry and tracing:

steps.ts

import { step } from '@outputai/core';
import { jina } from '../../clients/jina.js';
import { ScrapePageInput, ScrapePageOutput } from './types.js';

export const scrapePage = step({
  name: 'scrapePage',
  description: 'Scrape a web page using Jina Reader API',
  inputSchema: ScrapePageInput,
  outputSchema: ScrapePageOutput,
  fn: async (url) => {
    const response = await jina.get(url);
    const data = await response.json();

    return {
      title: data.data?.title ?? '',
      content: data.data?.content ?? '',
      url: data.data?.url ?? url
    };
  }
});

// types.ts
// import { z } from '@outputai/core';
//
// export const ScrapePageInput = z.string();
//
// export const ScrapePageOutput = z.object({
//   title: z.string(),
//   content: z.string(),
//   url: z.string()
// });

Tracing

All requests made with @outputai/http are automatically traced — no configuration needed. In your trace files, HTTP calls appear as children of the step that made them:

{
  "kind": "http",
  "name": "request",
  "input": { "method": "GET", "url": "https://r.jina.ai/https://acme.com" },
  "output": { "status": 200, "statusText": "OK" }
}

See Tracing for details on the trace format.

Attaching Request Cost

When you know the dollar cost of an HTTP request (for example from provider billing headers), you can attach it to the HTTP trace event with addRequestCost.

import { httpClient, addRequestCost } from '@outputai/http';

const client = httpClient( { prefixUrl: 'https://api.vendor.com' } );

const response = await client.post( 'search', {
  json: { query: 'acme' }
} );

const inputCost = Number( response.headers.get( 'x-cost-input-usd' ) ?? 0 );
const outputCost = Number( response.headers.get( 'x-cost-output-usd' ) ?? 0 );

addRequestCost( response, {
  total: inputCost + outputCost,
  components: [
    { name: 'input', value: inputCost },
    { name: 'output', value: outputCost }
  ]
} );

addRequestCost only works with responses created by @outputai/http (or its exported fetch). If the response did not come from this package, the function safely no-ops and logs a warning.

It also emits a cost:http:request hook event (same hooks system as cost:llm:request). For the payload and examples, see Cost Events — HTTP.

Error Handling

The client throws HTTPError for non-2xx responses and TimeoutError for timeouts:

import { HTTPError, TimeoutError } from '@outputai/http';

try {
  const response = await jina.get(url);
  return response.json();
} catch (error) {
  if (error instanceof HTTPError) {
    if (error.response.status === 404) {
      return null; // Page not found
    }
    // 429, 500, etc. — let the step retry
    throw error;
  }
  if (error instanceof TimeoutError) {
    throw error; // Step will retry
  }
  throw error;
}

Since steps retry automatically, you generally just need to handle cases where retrying won’t help (like a 404). For everything else, let the error propagate and the step’s retry policy will handle it.

Environment Variables

Variable	Description
OUTPUT_TRACE_HTTP_VERBOSE	Set to true or 1 to include request/response headers and bodies in trace files (otherwise only method, URL, and status are recorded)

API Reference

For complete TypeScript API documentation, see the HTTP Module API Reference.