> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expectedparrot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote caching

> Understand hosted response reuse and when to request new draws.

A remote cache stores model responses on Expected Parrot so matching calls can reuse them. It is separate from a [local Cache](https://docs.expectedparrot.com/en/latest/cache.md), a saved Results object, and the service that [executes a job](https://docs.expectedparrot.com/en/latest/remote_inference.md).

Use it to reuse responses across sessions without carrying a local cache file between environments. If your aim is simply to reopen completed data for analysis, retrieve the Results object; use the cache when running a job that may contain matching calls.

A matching question alone is insufficient for a cache hit. Model configuration, rendered system and user prompts, and iteration information matter. Changing a scenario, agent instruction, or model parameter can change the call even if the question object is unchanged.

## Control caching in Python

Remote caching follows your Expected Parrot account settings unless disabled for the run. With [authentication configured](https://docs.expectedparrot.com/en/latest/api_keys.md), inspect the setting in Python:

```python theme={null}
from edsl import Coop

coop = Coop()
coop.edsl_settings.get("remote_caching")
```

To run a prepared job with an explicit local cache and remote caching disabled:

```python theme={null}
from edsl import Cache, Jobs

job = Jobs.load("jobs.ep")
cache = Cache()
results = job.run(
    cache=cache,
    disable_remote_inference=True,
    disable_remote_cache=True,
)
results.select("answer.*", "cache_used.*")
# In a script, append .print() to display the table.
```

`disable_remote_inference=True` runs orchestration locally; a provider model still makes API calls and can incur costs. `disable_remote_cache=True` controls hosted cache access separately. Omitting it allows the account setting to apply. A `cache_used` value records response reuse; it does not identify whether the entry originally came from a local or remote cache.

## Request fresh responses

To request new model responses instead of reusing cached responses, use `fresh=True` with hosted execution:

```python theme={null}
fresh_results = job.run(offload_execution=True, fresh=True)
fresh_results.save("fresh-results.ep")
```

For local orchestration, start with a new `Cache()` and set `disable_remote_cache=True`, as in the example above. In this version, `fresh=True` alone does not bypass entries already in a supplied local cache.

## Download cache entries for a job

Use the remote **job UUID** from [Background jobs](https://docs.expectedparrot.com/en/latest/guides/background_jobs.md), rather than a Results object UUID. These calls require Expected Parrot access:

```python theme={null}
from edsl import Cache, Coop

coop = Coop()
entries = coop.remote_cache_get(job_uuid="JOB_UUID")  # Replace with your job UUID.
downloaded_cache = Cache(data={entry.key: entry for entry in entries})
downloaded_cache.write_jsonl("job-cache.jsonl")
downloaded_cache.select("model", "user_prompt", "output")
```

The return value from `remote_cache_get()` is a list of `CacheEntry` objects, not a Results object or a Cache. Constructing the Cache as above lets you inspect it, save it, or pass it as `cache=downloaded_cache` to a later run. Only matching model calls can reuse those entries. Save the full Results separately to retain the survey, answers, and study metadata.

## Download entries by cache key

When you already know the keys, retrieve a specific set instead of all entries for a job:

```python theme={null}
entries = coop.remote_cache_get_by_key(select_keys=["CACHE_KEY"])
# Replace CACHE_KEY with an actual key, for example one from cache.keys().
selected_cache = Cache(data={entry.key: entry for entry in entries})
```

`select_keys` must be a nonempty list. To merge retrieved entries into an existing local cache, use `cache.add_from_dict({entry.key: entry for entry in entries})`. Conflicting entries with the same key raise an error. Remote availability and account access still apply; do not assume every key can be retrieved.

## CLI alternatives

```bash theme={null}
ep settings
ep run jobs.ep --fresh --output fresh-results.ep
```

`ep settings` shows account settings. `--fresh` requests new responses for a run. These CLI commands complement the Python retrieval and cache-management methods above.

See [Jobs execution options](https://docs.expectedparrot.com/en/latest/jobs.md#execution-options) for controlling caching during a run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.