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:

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

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

Parameters

Union[str, UUID]

default:"'main_dataset'"

Local dataset name or UUID to push. Requires read permission.

Optional[str]

default:"None"

Dataset name on the remote instance. Defaults to the local dataset’s name.

str

default:"'preserve'"

Remote import fidelity. One of preserve, hybrid, or re-derive (see below).

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.

Optional[str]

default:"None"

Remote instance URL. Falls back to the active serve() connection, COGNEE_SERVICE_URL, or saved credentials.

Optional[str]

default:"None"

API key for the remote instance. Falls back like url.

User

default:"None"

Local user context for the export. Uses the default user when omitted.

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:

str

Status reported by the remote remember call (for example "started").

str

Name of the local dataset that was exported.

str

Dataset name the graph was imported into on the remote instance.

int

Number of nodes uploaded.

int

Number of edges uploaded.

Optional[str]

Remote migration pipeline run id; poll it when run_in_background=True.

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.

Reference

push()

cognee.push()

Description

Authentication

Parameters

Import modes

Returns

Examples

See also

​cognee.push()

​Description

​Authentication

​Parameters

​Import modes

​Returns

​Examples

​See also

cognee.push()

Description

Authentication

Parameters

Import modes

Returns

Examples

See also