Skip to main content

​
cognee.push()

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, 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(): 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.
The dataset must already have a knowledge graph. If the export finds 0 nodes, push() raises an error — run cognify() (or remember()) on the dataset first.

​
Authentication

push() reuses the serve() credential stack. Run cognee.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

​
dataset
Union[str, UUID]
default:"'main_dataset'"
Local dataset name or UUID to push. Requires read permission.
​
target_dataset
Optional[str]
default:"None"
Dataset name on the remote instance. Defaults to the local dataset’s name.
​
mode
str
default:"'preserve'"
Remote import fidelity. One of preserve, hybrid, or re-derive (see below).
​
run_in_background
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.
​
url
Optional[str]
default:"None"
Remote instance URL. Falls back to the active serve() connection, COGNEE_SERVICE_URL, or saved credentials.
​
api_key
Optional[str]
default:"None"
API key for the remote instance. Falls back like url.
​
user
User
default:"None"
Local user context for the export. Uses the default user when omitted.

​
Import modes

ModeRemote behaviorLLM calls
preserve (default)Map the exported entities and facts directly into the remote graphNone
hybridPreserve the exported graph and cognify the raw contentYes
re-deriveIgnore the exported graph; rebuild it from the raw content remotelyYes

​
Returns

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

​
Examples

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",
)
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() / remember() with raw data instead.

​
See also