Skip to main content
Your data is registered in the Files section of Index where it is organized into folders and sub-folders. Importing your data into Encord is a multi-step process:
  1. Set up a GCP integration.
  2. Create a GCP integration in Encord.
  3. Create a JSON or CSV.
  4. Create a folder to store your data in Encord.
  5. Upload your data to the folder.
See our GCP integration documentation for a detailed guide to setting up a GCP integration.

​
Step 1: Setup GCP Integration

Step 1: Setup GCP bucketStep 2: Configure CORS

​
Step 2: Create Encord Integration

Once your GCP storage is set up and configured, you are ready to create the integration in the Encord platform (https://app.encord.com/integrations or https://app.us.encord.com/integrations). In the Integrations section of the Encord platform, click +New integration to create a new integration.
Click + Add integration. Create the integration by selecting GCP at the top of the chooser. Enter a name for the integration, and enter the name of the bucket you wish to make available in the second dropdown of the GCP integration window.
Optionally check the box to enable Strict client-only access, server-side media features will not be available if you would like Encord to sign URLs, but refrain from downloading any media files onto Encord servers. Read more about this feature here.
Click Create to create the GCP integration.

​
Step 3: Create JSON or CSV for Registration

All types of data (videos, images, image groups, image sequences, and DICOM) from a private cloud are added to a Dataset in the same way, by using a JSON or CSV file. The file includes links to all images, image groups, videos and DICOM files in your cloud storage.
For a list of supported file formats for each data type, go here
Encord supports file names up to 300 characters in length for any file or video for upload.
Encord enforces the following upload limits for each JSON file used for file registration:
  • Up to 1 million URLs
  • A maximum of 500,000 items (e.g. images, image groups, videos, DICOMs)
  • URLs can be up to 16 KB in size
Optimal upload chunking can vary depending on your data type and the amount of associated metadata. For tailored recommendations, contact Encord support. We recommend starting with smaller uploads and gradually increasing the size based on how quickly jobs are processed. Generally, smaller chunks result in faster data reflection within the platform.
BEST PRACTICE: If you want to use Index or Active with your video data, we STRONGLY RECOMMEND using custom metadata (clientMetadata) to specify key frames, custom metadata, and custom embeddings. For more information go here or here for information on using the SDK.

​
Create JSON file for Registration

For detailed information about the JSON file format used for import go here. The information provided about each of the following data types is designed to get you up and running as quickly as possible without going too deeply into the why or how. Look at the template for each data type, then the examples, and adjust the examples to suit your needs.
If skip_duplicate_urls is set to true, all object URLs that exactly match existing images/videos in the dataset are skipped.

​
Videos

Video MetadataWhen the videoMetadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers.
To guarantee accurate labels, it is crucial that the videoMetadata provided is accurate.
{
  "videos": [
    {
      "objectUrl": "cloud-path-to-your-video-1"
    },
    {
      "objectUrl": "cloud-path-to-your-video-2",
        "videoMetadata": {
          "fps": frames-per-second,
          "duration": duration-in-seconds,
          "width": frame-width,
          "height": frame-height,
          "file_size": file-size-in-bytes,
          "mime_type": "MIME-file-type-extension"
        }
      }
  ],
  "skip_duplicate_urls": true
}

​
Audio Files

The following is an example JSON file for uploading two audio files to Encord.
  • Example 1 imports audio files with an Encord title.
  • Example 2 imports one audio file with the audiometadata flag. When the audiometadata flag is present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. To guarantee accurate labels, it is crucial that the metadata you provide is accurate.
{
  "audio": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-custom-audio-file-title.mp3"
    }
  ],
  "skip_duplicate_urls": true
}

​
PDFs

The following are example JSON files for uploading PDFs to Encord.
{
  "pdfs": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-document-02.pdf"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-document-03.pdf",
      "pdfMetadata": {
        "fileSize": 300,
        "numPages": 5
        }
    }
  ],
  "skip_duplicate_urls": true
}

​
Text Files

The following are example JSON files for uploading text files to Encord.
{
  "text": [
    {
      "objectUrl": "<object url_1>"
    },
    {
      "objectUrl": "<object url_2>",
      "title": "my-file.html"
    },
    {
      "objectUrl": "<object url_3>",
      "title": "my-plain-text-file.txt",
      "textMetadata": {
        "fileSize": 200,
        "mime_type": "text/plain"
      }
    },
    {
      "objectUrl": "<object url_4>",
      "title": "my-csv-file.csv",
      "textMetadata": {
        "fileSize": 250,
        "mime_type": "text/csv"
      }
    },
    {
      "objectUrl": "<object url_5>",
      "title": "my-xml-file.xml",
      "textMetadata": {
        "fileSize": 300,
        "mime_type": "application/xml"
      }
    },
    {
      "objectUrl": "<object url_6>",
      "title": "my-html-file.html",
      "textMetadata": {
        "fileSize": 400,
        "mime_type": "text/html"
      }
    }
  ],
  "skip_duplicate_urls": true
}

​
Single Images

For detailed information about the JSON file format used for import go here.The JSON structure for single images parallels that of videos.Template: Provides the proper JSON format to import images into Encord.Examples:
  • Data Imports the images only.
  • Image Metadata: Imports images with image metadata. This improves the import speed for your images. 
{
  "images": [
    {
      "objectUrl": "file/path/to/images/file-name-01.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-02.file-extension"
    },
    {
      "objectUrl": "file/path/to/images/file-name-03.file-extension",
      "title": "image-title.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

​
Image groups

For detailed information about the JSON file format used for import go here.
  • Image groups are collections of images that are processed as one annotation task.
  • Images within image groups remain unaltered, meaning that images of different sizes and resolutions can form an image group without the loss of data.
  • Image groups do NOT require ‘write’ permissions to your cloud storage.
  • If skip_duplicate_urls is set to true, all URLs exactly matching existing image groups in the dataset are skipped.
The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).
Template: Provides the proper JSON format to import image groups into Encord.Examples:
  • Data: Imports the image groups only.
{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension",
    },
    {
      "title": "<title 2>",
      "createVideo": false,
      "objectUrl_0": "file/path/to/images/file-name-01.file-extension",
      "objectUrl_1": "file/path/to/images/file-name-02.file-extension",
      "objectUrl_2": "file/path/to/images/file-name-03.file-extension"
    }
  ],
  "skip_duplicate_urls": true
}

​
Image sequences

For detailed information about the JSON file format used for import go here.
  • Image sequences are collections of images that are processed as one annotation task and represented as a video.
  • Images within image sequences may be altered as images of varying sizes and resolutions are made to match that of the first image in the sequence.
  • Creating Image sequences from cloud storage requires ‘write’ permissions, as new files have to be created in order to be read as a video.
  • Each object in the image_groups array with the createVideo flag set to true represents a single image sequence.
  • If skip_duplicate_urls is set to true, all URLs exactly matching existing image sequences in the dataset are skipped.
The only difference between adding image groups and image sequences using a JSON file is that image sequences require the createVideo flag to be set to true. Both use the key image_groups.
The position of each image within the sequence needs to be specified in the key (objectUrl_{position_number}).
Encord supports up to 32,767 entries (21:50 minutes) for a single image sequence. We recommend up to 10,000 to 15,000 entries for a single image sequence for best performance. If you need a longer sequence, we recommend using video instead of an image sequence.
Template: Provides the proper JSON format to import image groups into Encord.Examples:
  • Data: Imports the images groups only.
{
  "image_groups": [
    {
      "title": "<title 1>",
      "createVideo": true,
      "objectUrl_0": "<object url>"
    },
    {
      "title": "<title 2>",
      "createVideo": true,
      "objectUrl_0": "<object url>",
      "objectUrl_1": "<object url>",
      "objectUrl_2": "<object url>"
    }
  ],
  "skip_duplicate_urls": true
}

​
DICOM

For detailed information about the JSON file format used for import go here.
  • Each dicom_series element can contain one or more DICOM series.
  • Each series requires a title and at least one object URL, as shown in the example below.
  • If skip_duplicate_urls is set to true, all object URLs exactly matching existing DICOM files in the dataset will be skipped.
Custom metadata is distinct from patient metadata, which is included in the .dcm file and does not have to be specific during the upload to Encord.
The following is an example JSON for uploading three DICOM series belonging to a study. Each title and object URL correspond to individual DICOM series.
  • The first series contains only a single object URL, as it is composed of a single file.
  • The second series contains 3 object URLs, as it is composed of three separate files.
  • The third series contains 2 object URLs, as it is composed of two separate files.
For each DICOM upload, an additional DicomSeries file is created. This file represents the series file-set. Only DicomSeries are displayed in the Encord application.
JSON for DICOM
{
  "dicom_series": [
    {
      "title": "Series-1",
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series1-file.dcm"
    },
    {
      "title": "Series-2",
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file1.dcm",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file2.dcm",
      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series2-file3.dcm",
    },
      {
      "title": "Series-3",
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file1.dcm",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/study1-series3-file2.dcm",
    }
  ],
  "skip_duplicate_urls": true
}

​
NIfTI

The following is an example JSON file for uploading two NIfTI files to Encord.
{
    "nifti": [
      {
        "title": "<file-1>",
        "objectUrl": "https://my-bucket/.../nifti-file1.nii"
      },
      {
        "title": "<file-2>",
        "objectUrl": "https://my-bucket/.../nifti-file2.nii.gz"
      }
    ],
    "skip_duplicate_urls": true
  }
You can upload multiple file types using a single JSON file. The example below shows 1 image, 2 videos, 2 image sequences, and 1 image group.
Multiple file types

{
  "images": [
    {
      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/images/Image1.png"
    }
  ],
  "videos": [
    {
      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Cooking.mp4"
    },
    {
      "objectUrl": "https://storage.cloud.google.com/encord-image-bucket/videos/Oranges.mp4"
    }
  ],
  "image_groups": [
    {
      "title": "apple-samsung-light",
      "createVideo": true,
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/1+(32).jpg",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(33).jpg",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(34).jpg",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/1+(35).jpg"
    },
    {
      "title": "apple-samsung-dark",
      "createVideo": true,
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/2+(32).jpg",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/2+(33).jpg",
      "objectUrl_2": "https://storage.cloud.google.com/encord-image-bucket/images/2+(34).jpg",
      "objectUrl_3": "https://storage.cloud.google.com/encord-image-bucket/images/2+(35).jpg"
    }
  ],
  "image_groups": [
    {
      "title": "apple-ios-light",
      "createVideo": false,
      "objectUrl_0": "https://storage.cloud.google.com/encord-image-bucket/images/3+(32).jpg",
      "objectUrl_1": "https://storage.cloud.google.com/encord-image-bucket/images/3+(33).jpg"
    }
  ],
  "skip_duplicate_urls": true
}

​
Create CSV File for Registration

In the CSV file format, the column headers specify which type of data is being uploaded. You can add and single file format at a time, or combine multiple data types in a single CSV file. Details for each data format are given in the sections below.
Encord supports up to 10,000 entries for upload in the CSV file.
  • Object URLs can’t contain whitespace.
  • For backwards compatibility reasons, a single column CSV is supported. A file with the single ObjectUrl column is interpreted as a request for video upload. If your objects are of a different type (for example, images), this error displays: “Expected a video, got a file of type XXX”.

​
Videos

A CSV file containing videos should contain two columns with the following mandatory column headings:
‘ObjectURL’ and ‘Video title’. All headings are case-insensitive.
  • The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the video resource.
  • The ‘Video title’ column containing the video_title. If left blank, the original file name is used.
In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.
ObjectUrlVideo title
path/to/storage-location/frame1.mp4Video 1
path/to/storage-location/frame2.mp4Video 2
path/to/storage-location/frame3.mp4
path/to/storage-location/frame4.mp4Video 3
A CSV file containing single images should contain two columns with the following mandatory headings:
‘ObjectURL’ and ‘Image title’. All headings are case-insensitive.
  • The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the image resource.
  • The ‘Image title’ column containing the image_title. If left blank, the original file name is used.
In the example below files 1, 2 and 4 will be assigned the names in the title column, while file 3 will keep its original file name.
ObjectUrlImage title
path/to/storage-location/frame1.jpgImage 1
path/to/storage-location/frame2.jpgImage 2
path/to/storage-location/frame3.jpg
path/to/storage-location/frame4.jpgImage 3

​
Image groups

A CSV file containing image groups should contain three columns with the following mandatory headings:
‘ObjectURL’, ‘Image group title’, and ‘Create video’. All three headings are case-insensitive.
  • The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.
  • The ‘Image group title’ column containing the image_group_title. This field is mandatory, as it determines which image group a file will be assigned to.
In the example below the first two URLs are grouped together into ‘Group 1’, while the following two files are grouped together into ‘Group 2’.
ObjectUrlImage group titleCreate video
path/to/storage-location/frame1.jpgGroup 1false
path/to/storage-location/frame2.jpgGroup 1false
path/to/storage-location/frame3.jpgGroup 2false
path/to/storage-location/frame4.jpgGroup 2false
Image groups do not require ‘write’ permissions.

​
Image sequences

A CSV file containing image sequences should contain three columns with the following mandatory headings: ‘ObjectURL’, ‘Image group title’, and ‘Create video’. All three headings are case-insensitive.
  • The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.
  • The ‘Image group title’ column containing the image_group_title. This field is mandatory, as it determines which image sequence a file will be assigned to. The dimensions of the image sequence are determined by the first file in the sequence.
  • The ‘Create video’ column. This can be left blank, as the default value is ‘true’.
In the example below the first two URLs are grouped together into ‘Sequence 1’, while the second two files are grouped together into ‘Sequence 2’.
ObjectUrlImage group titleCreate video
path/to/storage-location/frame1.jpgSequence 1true
path/to/storage-location/frame2.jpgSequence 1true
path/to/storage-location/frame3.jpgSequence 2true
path/to/storage-location/frame4.jpgSequence 2true
Image groups and image sequences are only distinguished by the presence of the ‘Create video’ column.
Image sequences require ‘write’ permissions against your storage bucket to save the compressed video.
A CSV file containing DICOM files should contain two columns with the following mandatory headings: ‘ObjectURL’ and ‘Dicom title’. Both headings are case-insensitive.
  • The ‘ObjectURL’ column containing the objectUrl. This field is mandatory for each file, as it specifies the full URL of the resource.
  • The ‘Series title’ column containing the dicom_title. When two files are given the same title they are grouped into the same DICOM series. If left blank, the original file name is used.
In the example below the first two files are grouped into ‘dicom series 1’, the next two files are grouped into ‘dicom series 2’, while the final file will remain separated as ‘dicom series 3’.
ObjectUrlSeries title
path/to/storage-location/frame1.dcmdicom series 1
path/to/storage-location/frame2.dcmdicom series 1
path/to/storage-location/frame3.dcmdicom series 2
path/to/storage-location/frame4.dcmdicom series 2
path/to/storage-location/frame5.dcmdicom series 3

​
Multiple file types

You can upload multiple file types with a single CSV file by using a new header each time there is a change of file type. Three headings will be required if image sequences are included.
Since the ‘Create video’ column defaults to true all files that are not image sequences must contain the value false
The example below shows a CSV file for the following:
  • Two image sequences composed of 2 files each.
  • One image group composed of 2 files.
  • One single image.
  • One video.
ObjectUrlImage group titleCreate video
path/to/storage-location/frame1.jpgSequence 1true
path/to/storage-location/frame2.jpgSequence 1true
path/to/storage-location/frame3.jpgSequence 2true
path/to/storage-location/frame4.jpgSequence 2true
path/to/storage-location/frame5.jpgGroup 1false
path/to/storage-location/frame6.jpgGroup 1false
ObjectUrlImage titleCreate video
path/to/storage-location/frame1.jpgImage 1false
ObjectUrlImage titleCreate video
full/storage/path/video.mp4Video 1false

​
Step 4: Create a folder

  1. Navigate to Files section of Index in the Encord platform.
  2. Click + New folder. Select the type of folder you want to create.
  1. Give the folder a meaningful name and description.
  2. Click Create to create the folder. The folder is listed in Files.

​
Step 5: Upload your data to the folder

To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our limits and best practices for data import/registration before adding data to Encord.
  1. Navigate to Files section of Index in the Encord platform.
  2. Click + Upload files. A dialog appears.
  3. Select the folder you previously created.
  4. Click the Import from private cloud option.
  5. Select the integration you previously created to add your cloud data.
    We recommend turning on the Ignore individual file errors feature. This ensures that individual file errors do not lead to the whole upload process being aborted.
  6. Click Add JSON or CSV files to add a JSON or CSV file specifying cloud data that is to be added.
⌘I