# Proxy Methods

Fetch external content through the TelemetryOS proxy service to handle CORS restrictions with intelligent caching and bandwidth management.

# Proxy Methods

Fetch external content through the TelemetryOS proxy service.

## Overview

The Proxy Methods provide access to external content through the TelemetryOS platform, automatically handling CORS restrictions, caching, authentication, and bandwidth management across your device fleet.

> **About CORS:** TelemetryOS applications run in browser contexts where Cross-Origin Resource Sharing (CORS) policies apply. The Proxy API solves CORS limitations by routing requests through the TelemetryOS platform. For complete CORS information, see **[Understanding CORS](../development/cors.md)**.

## Importing

```typescript
import { proxy } from '@telemetryos/sdk';
```

## Methods

### fetch()

Fetch content from external URLs through the platform proxy.

**Signature:**

```typescript
async fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
```

**Parameters:**

* `input` - URL as string, URL object, or Request object
* `init` - Optional fetch options (method, headers, body, etc.)

**Returns:** `Promise<Response>` - Standard Response object

**Example:**

```typescript
const response = await proxy().fetch('https://api.example.com/data');
const data = await response.json();
```

## Caching Behavior

The TelemetryOS proxy implements intelligent caching to optimize performance across device fleets.

### Default Caching

* **GET requests**: 60-second cache by default
* **Other methods**: No default caching

### Why Caching Matters

When hundreds or thousands of devices request the same external content simultaneously, the proxy cache prevents overwhelming external servers thus preventing you from being rate limited or blocked. Always use caching whenever possible.

### Controlling Cache with Headers

Control proxy caching using standard `Cache-Control` request headers:

```typescript
// Force fresh fetch (bypass cache)
const response = await proxy().fetch('https://api.example.com/data', {
  headers: { 'Cache-Control': 'no-cache' }
});
```

**Common directives:** `no-cache` (bypass cache), `no-store` (never cache), `max-age=<seconds>` (custom cache duration).

## Next Steps

* **[Understanding CORS](../development/cors.md)** - Learn about CORS and why Proxy is needed
* **[Storage Methods](./storage-methods.md)** - Cache external data locally
* **[Weather Methods](./weather-methods.md)** - Weather data through TelemetryOS API
* **[Code Examples](../development/code-examples.md)** - Complete proxy integration examples