# Smart-Cache Proxy: AI & B2B API Cost Optimizer (`riad_h/smart-cache-proxy`) Actor

Ultra-fast caching middleware proxy for AI & B2B APIs. Hashes and caches identical request payloads using Apify's Key-Value Store, eliminating redundant API hits and slashing your monthly API bills by 50-80%.

- **URL**: https://apify.com/riad\_h/smart-cache-proxy.md
- **Developed by:** [Riad Hossain](https://apify.com/riad_h) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Smart-Cache Proxy: AI & B2B API Cost Optimizer

> Ultra-fast caching middleware that sits between your application and expensive APIs (OpenAI, Claude, Google Maps, scraping endpoints). Identical requests are served from cache — **slashing your API bills by 50-80%** with microsecond-level responses.

### How It Works

```
Your App  →  Smart-Cache Proxy  →  Expensive API (OpenAI, Claude, etc.)
                    ↓
              Apify Key-Value Store
              (persistent cache)
```

1. Your app sends a request to the proxy (instead of the upstream API)
2. The proxy generates a SHA-256 fingerprint of the request (method + URL + body)
3. If the response is cached and not expired → **instant cache HIT** (no upstream call)
4. If not cached → forwards to the upstream API, caches the response, returns it
5. The `X-Cache: HIT` or `X-Cache: MISS` header tells you exactly what happened

### Key Features

- **SHA-256 Request Fingerprinting** — deterministic hashing with stable key ordering, so `{a:1, b:2}` and `{b:2, a:1}` produce the same cache key
- **Zero Infrastructure** — uses Apify's built-in Key-Value Store. No Redis, no database, no maintenance
- **Bearer Token Pass-Through** — your API keys are forwarded to the upstream API but never stored or logged by the proxy
- **X-Cache Headers** — every response includes `X-Cache: HIT` or `X-Cache: MISS` so you can monitor savings in real-time
- **Configurable TTL** — set cache expiration per deployment (1 second to 7 days)
- **Only Caches Success** — 2xx JSON responses are cached; errors (4xx, 5xx) are never cached
- **All HTTP Methods** — supports GET, POST, PUT, PATCH, DELETE

### Input Configuration

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `targetUrl` | string | ✅ | `https://api.openai.com/v1` | The upstream API base URL to proxy |
| `cacheTtlSeconds` | integer | ❌ | `86400` (24h) | Cache time-to-live in seconds |
| `requestTimeoutMs` | integer | ❌ | `30000` | Upstream request timeout |
| `maxBodySizeMb` | integer | ❌ | `10` | Max request body size |

### Quick Start

#### 1. Configure the Actor

Set `targetUrl` to the API you want to proxy. For example:

- OpenAI: `https://api.openai.com/v1`
- Anthropic: `https://api.anthropic.com/v1`
- Google Maps: `https://maps.googleapis.com/maps/api`

#### 2. Get your proxy URL

After running the Actor (or enabling Standby mode), you'll get a URL like:

```
https://api.apify.com/v2/acts/riad_h~smart-cache-proxy/runs/:runId
```

#### 3. Point your client at the proxy

**OpenAI SDK (Python):**

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key-here",  # Stays 100% private
    base_url="https://your-proxy-url.apify.net/v1"  # Smart-Cache Proxy
)

## First call → X-Cache: MISS (forwards to OpenAI, caches response)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Extract emails from this text..."}]
)

## Second identical call → X-Cache: HIT (instant, $0.00 cost!)
response2 = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Extract emails from this text..."}]
)
```

**OpenAI SDK (Node.js):**

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://your-proxy-url.apify.net/v1"
});
```

**cURL:**

```bash
## First call — cache MISS
curl -X POST https://your-proxy-url/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
## → X-Cache: MISS

## Same payload — cache HIT (no upstream call!)
curl -X POST https://your-proxy-url/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
## → X-Cache: HIT
```

### Management Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/__health` | GET | Check proxy status and configuration |
| `/__cache_stats` | GET | View cache hit/miss counts and hit rate |
| `/__cache` | DELETE | Clear all cached entries |

**Example:**

```bash
curl https://your-proxy-url/__cache_stats
## {"hits": 1247, "misses": 893, "totalRequests": 2140, "hitRate": "58.27%"}
```

### Response Headers

| Header | Value | Description |
|---|---|---|
| `X-Cache` | `HIT` or `MISS` | Whether the response was served from cache |
| `X-Cache-Key` | `<16-char hex>` | First 16 chars of the SHA-256 cache key |
| `X-Cache-Expires` | ISO timestamp | When the cached entry expires (HIT only) |
| `X-Response-Time-ms` | integer | Server-side processing time (MISS only) |

### Use Cases

1. **AI Cost Optimization** — cache identical LLM completions to avoid paying for the same prompt twice
2. **Duplicate Query Elimination** — cache API responses for common queries
3. **Rate Limit Avoidance** — serve cached responses instead of hitting rate-limited APIs
4. **Response Acceleration** — cached responses return in <5ms instead of 500-3000ms
5. **Development & Testing** — cache API responses during development to avoid burning credits

### Privacy & Security

- Your API keys (Bearer tokens, x-api-key) are **passed through** to the upstream API but **never stored** in the cache or logs
- Only the API response data is cached — never headers, auth tokens, or request metadata
- The proxy runs on Apify's secure infrastructure with full isolation

### Pricing

This Actor uses **pay-per-event** billing:

| Event | Charged When | Suggested Price |
|---|---|---|
| `cache-hit` | A request is served from cache (saving you an upstream API call) | $0.001 per hit |
| `cache-miss` | A request is forwarded to the upstream API (and cached) | $0.01 per miss |

You only pay when the proxy delivers value (cache hits). Configure pricing in the Actor's Monetization tab.

### Technical Details

- **Runtime:** Node.js 20 + Express + axios
- **Cache:** Apify Key-Value Store (named store `smart-cache-proxy` for persistence across container restarts)
- **Hashing:** SHA-256 with stable JSON key ordering
- **TTL:** Enforced on read — expired entries are treated as misses and replaced
- **Response parsing:** Auto-detects JSON vs text responses; only caches successful JSON

### License

MIT

# Actor input Schema

## `targetUrl` (type: `string`):

The expensive API endpoint you want to proxy (e.g. https://api.openai.com/v1, https://api.anthropic.com/v1, https://maps.googleapis.com/maps/api). All request paths are appended to this base URL.

## `cacheTtlSeconds` (type: `integer`):

How long should matching API responses be cached, in seconds. Default: 86400 (24 hours). Set lower for frequently-changing data, higher for stable data.

## `requestTimeoutMs` (type: `integer`):

Timeout for forwarding requests to the upstream API, in milliseconds. Default: 30000 (30s).

## `maxBodySizeMb` (type: `integer`):

Maximum size of request bodies accepted by the proxy, in megabytes. Default: 10.

## Actor input object example

```json
{
  "targetUrl": "https://api.openai.com/v1",
  "cacheTtlSeconds": 86400,
  "requestTimeoutMs": 30000,
  "maxBodySizeMb": 10
}
```

# Actor output Schema

## `health` (type: `string`):

Check if the proxy is running and view configuration.

## `stats` (type: `string`):

View cache hit/miss rates and total requests served.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "targetUrl": "https://api.openai.com/v1",
    "cacheTtlSeconds": 86400,
    "requestTimeoutMs": 30000,
    "maxBodySizeMb": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("riad_h/smart-cache-proxy").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "targetUrl": "https://api.openai.com/v1",
    "cacheTtlSeconds": 86400,
    "requestTimeoutMs": 30000,
    "maxBodySizeMb": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("riad_h/smart-cache-proxy").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "targetUrl": "https://api.openai.com/v1",
  "cacheTtlSeconds": 86400,
  "requestTimeoutMs": 30000,
  "maxBodySizeMb": 10
}' |
apify call riad_h/smart-cache-proxy --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,riad_h/smart-cache-proxy"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/67gvXIGtXNUmdmEy9/builds/CXm3s5z3dzUcWaiXW/openapi.json