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
The ID of the file upload to retrieve.
Response
Returns a FileUploadObjectResponse with the current state of the file upload.
Unique identifier for the file upload.
Current status of the file upload.Values: "pending" | "processing" | "complete" | "failed"
ISO 8601 timestamp when the file upload was created.
ISO 8601 timestamp when the file upload was last updated.
File information (only present when status is "complete")
The Notion URL where the file can be accessed.
ISO 8601 timestamp when the file URL will expire.
Name of the uploaded 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
}
}
