Retrieve file upload

Get details about a specific file upload by ID

Retrieves the details of an existing file upload. This is useful for checking the status of an upload or getting the file URL after completion.

Method

client.fileUploads.retrieve({
  file_upload_id: "7c6a28216bb14a7eb6e1c50111515c3d"
})

Parameters

file_upload_id · string · required

The ID of the file upload to retrieve.

Response

Returns a FileUploadObjectResponse with the current state of the file upload.

object · string

Always "file_upload"

id · string

Unique identifier for the file upload.

status · string

Current status of the file upload.

Values: "pending" | "processing" | "complete" | "failed"

created_time · string

ISO 8601 timestamp when the file upload was created.

last_edited_time · string

ISO 8601 timestamp when the file upload was last updated.

file · object

File information (only present when status is "complete")

Show file properties

url · string

The Notion URL where the file can be accessed.

expiry_time · string

ISO 8601 timestamp when the file URL will expire.

filename · string

Name of the uploaded file.

content_type · string

MIME type of the file.

Examples

Check upload status

const { Client } = require('@notionhq/client')

const notion = new Client({ auth: process.env.NOTION_TOKEN })

const fileUpload = await notion.fileUploads.retrieve({
  file_upload_id: "7c6a28216bb14a7eb6e1c50111515c3d"
})

console.log(`Status: ${fileUpload.status}`)

if (fileUpload.status === "complete" && fileUpload.file) {
  console.log(`File URL: ${fileUpload.file.url}`)
}

Poll for completion

async function waitForUpload(fileUploadId) {
  let upload
  
  do {
    upload = await notion.fileUploads.retrieve({
      file_upload_id: fileUploadId
    })
    
    if (upload.status === "failed") {
      throw new Error("File upload failed")
    }
    
    if (upload.status !== "complete") {
      // Wait 1 second before checking again
      await new Promise(resolve => setTimeout(resolve, 1000))
    }
  } while (upload.status !== "complete")
  
  return upload
}

const completedUpload = await waitForUpload("7c6a28216bb14a7eb6e1c50111515c3d")
console.log(`File ready: ${completedUpload.file.url}`)

Get file URL with error handling

try {
  const upload = await notion.fileUploads.retrieve({
    file_upload_id: fileUploadId
  })
  
  if (upload.status === "complete" && upload.file) {
    return upload.file.url
  } else {
    throw new Error(`Upload not complete: ${upload.status}`)
  }
} catch (error) {
  if (error.code === APIErrorCode.ObjectNotFound) {
    console.error("File upload not found")
  } else {
    throw error
  }
}

Related methods

• Create file upload
• Send file upload
• Complete file upload
• List file uploads