Skip to content

getstream import

Bulk-import chat or feeds data into your app from a prepared JSON Lines file. The file is uploaded to Stream and processed in the background as an import task; the status and list subcommands track those tasks.

getstream import chat <file>
getstream import feeds <file>
getstream import status <id>
getstream import list

Commands use the initialized project's credentials by default. Pass --app-id to target another app you own (requires login), or set STREAM_API_KEY and STREAM_API_SECRET to supply credentials directly. --app-id works on every subcommand.

getstream import chat

getstream import chat export.jsonl
getstream import chat export.jsonl --watch

Uploads the file and creates a chat import task, printing the task as JSON. Imports run in upsert mode, the only mode the CLI offers.

The file format is JSON Lines: one object per line, of type user, device, future_channel_ban, channel, member, message, reaction, poll, or poll_vote, in that order. See Import chat data for the format and its validation rules.

Flag Effect
--merge-custom Merge custom data during import. Only sent to the server when passed explicitly.
-w, --watch Follow the import task until it finishes.
--app-id <id> Target an app you own instead of the initialized project. Requires login.

getstream import feeds

getstream import feeds export.jsonl
getstream import feeds export.jsonl --skip-references-check
getstream import feeds export.jsonl --watch

Uploads the file and creates a feeds import task, printing the task as JSON.

The file format is JSON Lines: each line is an envelope, { "type": "<entity>", "data": { ... } }. See Importing data into feeds for the entity types and full schemas.

Flag Effect
--skip-references-check Skip references validation for the import.
-w, --watch Follow the import task until it finishes.
--app-id <id> Target an app you own instead of the initialized project. Requires login.

By default, validation requires every referenced object (for example an activity's user_id) to appear in the file or already exist in the app, and fails the import otherwise. Pass --skip-references-check when you deliberately import a partial dataset whose references live outside the file.

getstream import status

getstream import status dcb6e366-93ec-4e52-af6f-b0c030ad5272
getstream import status dcb6e366-93ec-4e52-af6f-b0c030ad5272 --watch

Prints an import task by ID as JSON, for chat and feeds imports alike. The task's state field is one of the values below.

Flag Effect
-w, --watch Keep polling until the import finishes.
--app-id <id> Target an app you own instead of the initialized project. Requires login.

getstream import list

getstream import list
getstream import list --state 4

Lists the app's import tasks, chat and feeds alike, as JSON.

Flag Effect
-s, --state <n> Filter tasks by state, using the values below.
--app-id <id> Target an app you own instead of the initialized project. Requires login.

Task states

State Meaning
1 queued
2 processing
3 failed
4 completed

Behavior

  • The upload is an HTTP PUT to a presigned URL the API issues for the file. In a terminal, a progress bar with ETA renders on stderr, so large uploads are not opaque.
  • --watch polls the task every 5 seconds and reprints the task JSON whenever its state changes. It exits 0 when the task completes and non-zero with import failed when it fails. Interrupting the watch stops the polling only; the server keeps processing the import.
  • Output is JSON on stdout, formatted the same way as getstream api responses: when stdin is not a terminal, long arrays are shortened, with a notice on stderr.

Errors

  • no app credentials: run the command from a directory linked with getstream init, pass --app-id, or set STREAM_API_KEY and STREAM_API_SECRET. Setting only one of the two variables errors and names the missing one.
  • upload failed: <status>: the file transfer to the presigned URL was rejected; the response body is included.
  • A task in state 3 failed server-side validation or processing; import status <id> shows the task with the server's error details. The most common validation failure is a reference to an object that neither appears in the file nor exists in the app - fix the file, or for feeds imports pass --skip-references-check if the missing references are intentional.

See also