Skip to main content

Track Upload Status

In Swarm, an instruction to upload data to the network goes through 3 consecutive stages before it is completed:

  • Splitting
  • Storing
  • Sending

In the splitting state, the file is deconstructed in chunks (Swarms canonical data unit) and packaged in a Binary Merkle Tree. After splitting, the chunks are stored in your local database where they enter a queue, to be sent to the network.

Sending starts immediately when the first chunks are split and stored. After the chunk is sent, your node will receive a receipt from the node that has stored the chunk, marking the completion of the upload for that chunk. After a receipt has been received for all chunks, the upload is complete.

What is a tag

The status of your upload can be followed by using tags. A tag is a label given to all chunks that belong to the same upload instruction. In the bee-js library, tag looks as follows:

interface Tag {
total: number // the total number of chunks for upload(s) related with this tag
processed: number // the total number of chunks stored and queued for sending
synced: number // the total number of chunks that are synced with the network

uid: number // a unique identifier for this tag
startedAt: string // when the tag was first used

Create tag


Tags are automatically created on most upload methods and are returned using the UploadResult interface, so you don't have to create them manually most of the time.

Forbidden on Gateways

If you are using a node that is in Gateway mode then this operation is not allowed!

Creating a tag is easy. Just use the createTag function.

const tag = await bee.createTag()

Upload with tag

You can then use the tag when uploading data, by providing it in the options arguments for each of these methods.

const postageBatchId = getOrCreatePostageBatch()

await bee.uploadData(postageBatchId, "Bee is awesome!", { tag })
// OR
await bee.uploadFile(postageBatchId, file, "foo.txt", { tag })
// OR
await bee.uploadFiles(postageBatchId, files, { tag })
// OR
await bee.uploadFilesFromDirectory(postageBatchId, "./", { tag })

Retrieve tag

Forbidden on Gateways

If you are using a node that is in Gateway mode then this operation is not allowed!

Each time you want to check the upload status, you can use the retrieveTag function.

const updatedTag = await bee.retrieveTag(tag)
// OR
const updatedTag = await bee.retrieveTag(tag.uid)