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

# push()

> Upload a local dataset's knowledge graph to Cognee Cloud

# cognee.push()

```python theme={null}
async def push(
    dataset: Union[str, UUID] = "main_dataset",
    *,
    target_dataset: Optional[str] = None,
    mode: str = "preserve",
    run_in_background: bool = False,
    url: Optional[str] = None,
    api_key: Optional[str] = None,
    user: User = None,
) -> PushResult
```

## Description

Upload a local dataset's **already-built knowledge graph** to a Cognee Cloud (or
any remote Cognee) instance.

The dataset's graph is exported to a [COGX archive](/core-concepts/further-concepts/cogx),
packed as a tarball, uploaded, and imported on the remote instance — preserving
the entities and relationships you extracted locally instead of re-deriving them
from the raw files.

This is what distinguishes `push()` from [`sync()`](/cognee-cloud/connections/syncing-local-instance):
`push()` ships the **graph** so the remote side does little or no LLM work, while
`sync()` ships the **raw data** and the remote instance rebuilds the graph itself.

<Note>
  The dataset must already have a knowledge graph. If the export finds 0 nodes,
  `push()` raises an error — run [`cognify()`](/python-api/cognify) (or
  [`remember()`](/python-api/remember)) on the dataset first.
</Note>

## Authentication

`push()` reuses the `serve()` credential stack. Run [`cognee.serve()`](/python-api/serve)
(or `cognee-cli serve`) once to log in, then push any time. The remote target is
resolved in this order:

1. Explicit `url` / `api_key` arguments
2. An active `cognee.serve()` connection
3. `COGNEE_SERVICE_URL` / `COGNEE_API_KEY` environment variables
4. Saved credentials from a previous `serve()` login (`~/.cognee/cloud_credentials.json`)

If none resolve, `push()` raises a `RuntimeError` telling you to authenticate.

## Parameters

<ParamField path="dataset" type="Union[str, UUID]" default="'main_dataset'">Local dataset name or UUID to push. Requires read permission.</ParamField>
<ParamField path="target_dataset" type="Optional[str]" default="None">Dataset name on the remote instance. Defaults to the local dataset's name.</ParamField>
<ParamField path="mode" type="str" default="'preserve'">Remote import fidelity. One of `preserve`, `hybrid`, or `re-derive` (see below).</ParamField>
<ParamField path="run_in_background" type="bool" default="False">If true, the remote import is scheduled and the call returns once the upload completes; poll the returned `pipeline_run_id` for progress. Recommended for large graphs.</ParamField>
<ParamField path="url" type="Optional[str]" default="None">Remote instance URL. Falls back to the active `serve()` connection, `COGNEE_SERVICE_URL`, or saved credentials.</ParamField>
<ParamField path="api_key" type="Optional[str]" default="None">API key for the remote instance. Falls back like `url`.</ParamField>
<ParamField path="user" type="User" default="None">Local user context for the export. Uses the default user when omitted.</ParamField>

## Import modes

| Mode                   | Remote behavior                                                     | LLM calls |
| ---------------------- | ------------------------------------------------------------------- | --------- |
| `preserve` *(default)* | Map the exported entities and facts directly into the remote graph  | None      |
| `hybrid`               | Preserve the exported graph **and** cognify the raw content         | Yes       |
| `re-derive`            | Ignore the exported graph; rebuild it from the raw content remotely | Yes       |

## Returns

A `PushResult` dataclass:

<ParamField path="status" type="str">Status reported by the remote remember call (for example `"started"`).</ParamField>
<ParamField path="dataset_name" type="str">Name of the local dataset that was exported.</ParamField>
<ParamField path="target_dataset" type="str">Dataset name the graph was imported into on the remote instance.</ParamField>
<ParamField path="num_nodes" type="int">Number of nodes uploaded.</ParamField>
<ParamField path="num_edges" type="int">Number of edges uploaded.</ParamField>
<ParamField path="pipeline_run_id" type="Optional[str]">Remote migration pipeline run id; poll it when `run_in_background=True`.</ParamField>
<ParamField path="remote_response" type="dict">Raw response returned by the remote remember endpoint.</ParamField>

```python theme={null}
from cognee import PushResult
```

## Examples

```python theme={null}
import cognee

# Build a graph locally, then push it to the cloud
await cognee.remember("docs/handbook.pdf", dataset="onboarding")

# Log in once (opens a browser); credentials are reused afterwards
await cognee.serve()

# Push the default dataset (main_dataset)
result = await cognee.push()

# Push a named dataset
result = await cognee.push("onboarding")
print(result.num_nodes, result.num_edges)

# Push to a different dataset name on the remote instance
await cognee.push("onboarding", target_dataset="prod_onboarding")

# Preserve the graph AND re-cognify the raw content on the remote side
await cognee.push("onboarding", mode="hybrid")

# Large graph: schedule the remote import and return after the upload
result = await cognee.push("onboarding", run_in_background=True)
print(result.pipeline_run_id)  # poll this for progress

# Push to an explicit instance without a prior serve() login
await cognee.push(
    "onboarding",
    url="https://your-instance.cognee.ai",
    api_key="your-api-key",
)
```

<Note>
  The remote instance must run a Cognee version with COGX archive import support.
  Against an older server the upload is accepted but ingested as a plain file; `push()`
  detects this and raises an error rather than silently degrading. Upgrade the remote
  instance, or use [`sync()`](/cognee-cloud/connections/syncing-local-instance) /
  [`remember()`](/python-api/remember) with raw data instead.
</Note>

## See also

* [Syncing a Local Instance](/cognee-cloud/connections/syncing-local-instance) — connect the SDK to a remote instance and ship raw data with `sync()`
* [Cognee CLI → Push to Cloud](/cognee-cli/overview#push-to-cloud) — the same operation from the terminal (`cognee push`)