---
title: "take a table previously pushed from lakeFS into a remote catalog, and pull its state back into the originating lakeFS repository"
method: POST
path: "/iceberg/remotes/{catalog}/pull"
tags: ["remotes"]
---

# take a table previously pushed from lakeFS into a remote catalog, and pull its state back into the originating lakeFS repository

`POST /iceberg/remotes/{catalog}/pull`

## Request body

- IcebergPullRequest
  - `source` IcebergRemoteTable, required
    - `namespace` string[], required — Reference to one or more levels of a namespace
    - `table` string, required — Remote table name
  - `destination` IcebergLocalTable, required
    - `namespace` string[], required — Reference to one or more levels of a namespace
    - `table` string, required — Remote table name
    - `repository_id` string, required — lakeFS repository ID
    - `reference_id` string, required — lakeFS reference ID (branch or commit)
  - `force_update` boolean — Override exiting local table if exists
  - `create_namespace` boolean — Creates namespace in local catalog if not exist

## Response `204`

successfully pulled table from remote

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Resource Not Found
- `default` — Internal Server Error

## Changes

- **2025-11-24** `add5a8870f32` — 1 info
  - added the non-success response with the status `400`
- **2025-11-15** `82079c8c5ce2` — 2 info
  - added the new optional request property `create_namespace`
  - added the new optional request property `force_update`
- **2025-11-02** `3655468eca84` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/treeverse/apis/lakefs-api/changes/iceberg/remotes/:catalog/pull/post.md)

---

[API](https://skmtc.dev/treeverse/apis/lakefs-api.md) · [All operations](https://skmtc.dev/treeverse/apis/lakefs-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/treeverse/lakefs-api/revisions/f8c05f0eb0bb/schema)