Export conversational text annotations

How to export conversational text data and sample export formats.

Open this Colab for an interactive tutorial on exporting annotations.

πŸ“˜

Deprecating Export V1

Starting in April 2024, we will begin sunsetting Export V1 for customers on a rolling basis. For more details, see this guide.

Export JSON annotations

# Set the export params to include/exclude certain fields. Make sure each of these fields are correctly grabbed 
export_params= {
  "attachments": True,
  "metadata_fields": True,
  "data_row_details": True,
  "project_details": True,
  "label_details": True,
  "performance_details": True
}

# You can set the range for last_activity_at and label_created_at. 
# For context, last_activity_at captures the creation and modification of labels, metadata, status, comments and reviews.
# Note: This is an AND logic between the filters, so usually using one filter is sufficient.

filters= {
  "last_activity_at": ["2000-01-01 00:00:00", "2050-01-01 00:00:00"],
}

export_task = project.export_v2(params=export_params, filters=filters)
export_task.wait_till_done()

if export_task.errors:
  print(export_task.errors)

export_json = export_task.result
print("results: ", export_json)
# Set the export params to include/exclude certain fields. 
export_params= {
  "attachments": True,
  "metadata_fields": True,
  "data_row_details": True,
  "project_details": True,
  "label_details": True,
  "performance_details": True,
  "interpolated_frames": True
}

# Note: Filters follow AND logic, so typically using one filter is sufficient.
filters= {
  "last_activity_at": ["2000-01-01 00:00:00", "2050-01-01 00:00:00"],
  "workflow_status": "<wkf-status>"
}

client.enable_experimental = True

export_task = project.export(params=export_params, filters=filters)
export_task.wait_till_done()


# Return JSON output strings from export task results/errors, one by one:

# Callback used for JSON Converter
def json_stream_handler(output: lb.JsonConverterOutput):
  print(output.json_str)


if export_task.has_errors():
  export_task.get_stream(
  
  converter=lb.JsonConverter(),
  stream_type=lb.StreamType.ERRORS
  ).start(stream_handler=lambda error: print(error))

if export_task.has_result():
  export_json = export_task.get_stream(
    converter=lb.JsonConverter(),
    stream_type=lb.StreamType.RESULT
  ).start(stream_handler=json_stream_handler)

print("file size: ", export_task.get_total_file_size(stream_type=lb.StreamType.RESULT))
print("line count: ", export_task.get_total_lines(stream_type=lb.StreamType.RESULT))
     

Annotation export formats

Text entity (named entity)

{
  "feature_id": "cluu14r3p0oty148p5d2isiki",
  "feature_schema_id": "cluu14fnh01f40703aigj669b",
  "name": "ner",
  "value": "ner",
  "annotation_kind": "ConversationalTextEntity",
  "classifications": [],
  "conversational_location": {
    "message_id": "4",
    "location": {
      "start": 0,
      "end": 8
    }
  }
}

Classification - Radio

{
  "feature_id": "cluu14r3p0ou3148p6d15q82b",
  "feature_schema_id": "cluu14fnh01fe0703abp5fjgx",
  "name": "radio_convo",
  "value": "radio_convo",
  "message_id": "0",
  "conversational_radio_answer": {
    "feature_id": "cluu14r3p0ou4148pc028jtzk",
    "feature_schema_id": "cluu14fnh01ff070383rh4ryk",
    "name": "first_radio_answer",
    "value": "first_radio_answer",
    "classifications": []
  }
}

Classification - Checklist

{
  "feature_id": "cluu14r3p0ou0148ptekhuz0a",
  "feature_schema_id": "cluu14fnh01f8070385tv57vy",
  "name": "checklist_convo",
  "value": "checklist_convo",
  "message_id": "2",
  "conversational_checklist_answers": [
    {
      "feature_id": "cluu14r3p0ou1148p8pb3s49a",
      "feature_schema_id": "cluu14fnh01f90703cx3j6gqu",
      "name": "first_checklist_answer",
      "value": "first_checklist_answer",
      "classifications": []
    },
    {
      "feature_id": "cluu14r3p0ou2148ph8tyhtp1",
      "feature_schema_id": "cluu14fnh01fb07030q2m5hqc",
      "name": "second_checklist_answer",
      "value": "second_checklist_answer",
      "classifications": []
    }
  ]
}

Classification - Free-form text

{
  "feature_id": "clr0x0ol83tvq07ea8f5phc2g",
  "feature_schema_id": "clpk2me9u02vx07xnet21fsgf",
  "name": "free_text",
  "text_answer": {
    "content": "sample text"
  }
}

Sample project export

{
  "data_row": {
    "id": "clfbnskoxb9q9076fbyjngwhm",
    "global_key": "conversation-1.json",
    "row_data": "https://storage.googleapis.com/labelbox-developer-testing-assets/conversational_text/1000-conversations/conversation-1.json",
    "details": {
      "dataset_id": "clfbnsjaj05hr07z605db0w3b",
      "dataset_name": "conversational_annotation_import_demo_dataset",
      "created_at": "2023-03-16T22:04:33.000+00:00",
      "updated_at": "2024-01-18T19:10:53.352+00:00",
      "last_activity_at": "2024-04-10T16:33:23.000+00:00",
      "created_by": "[email protected]"
    }
  },
  "media_attributes": {
    "mime_type": "application/vnd.labelbox.conversational",
    "labelable_ids": [
      "0",
      "2",
      "4",
      "6",
      "8",
      "10",
      "12",
      "14",
      "16",
      "18"
    ],
    "message_count": 20
  },
  "attachments": [],
  "metadata_fields": [],
  "projects": {
    "cluu14fwi01g0070321g9c1xi": {
      "name": "Conversational Text Annotation Import Demo",
      "labels": [
        {
          "label_kind": "Default",
          "version": "1.0.0",
          "id": "cluu14r490oud148pdk29bwes",
          "label_details": {
            "created_at": "2024-04-10T16:33:23.000+00:00",
            "updated_at": "2024-04-10T16:33:23.000+00:00",
            "created_by": "[email protected]",
            "content_last_updated_at": "2024-04-10T16:33:23.063+00:00",
            "reviews": []
          },
          "performance_details": {
            "seconds_to_create": 0,
            "seconds_to_review": 0,
            "skipped": false
          },
          "annotations": {
            "objects": [
              {
                "feature_id": "cluu14r3p0oty148p5d2isiki",
                "feature_schema_id": "cluu14fnh01f40703aigj669b",
                "name": "ner",
                "value": "ner",
                "annotation_kind": "ConversationalTextEntity",
                "classifications": [],
                "conversational_location": {
                  "message_id": "4",
                  "location": {
                    "start": 0,
                    "end": 8
                  }
                }
              }
            ],
            "classifications": [
              {
                "feature_id": "cluu14r3p0otz148p09nol3tq",
                "feature_schema_id": "cluu14fnh01f60703b4uadjbd",
                "name": "text_convo",
                "value": "text_convo",
                "message_id": "0",
                "conversational_text_answer": {
                  "content": "the answer to the text questions right here"
                }
              },
              {
                "feature_id": "cluu14r3p0ou0148ptekhuz0a",
                "feature_schema_id": "cluu14fnh01f8070385tv57vy",
                "name": "checklist_convo",
                "value": "checklist_convo",
                "message_id": "2",
                "conversational_checklist_answers": [
                  {
                    "feature_id": "cluu14r3p0ou1148p8pb3s49a",
                    "feature_schema_id": "cluu14fnh01f90703cx3j6gqu",
                    "name": "first_checklist_answer",
                    "value": "first_checklist_answer",
                    "classifications": []
                  },
                  {
                    "feature_id": "cluu14r3p0ou2148ph8tyhtp1",
                    "feature_schema_id": "cluu14fnh01fb07030q2m5hqc",
                    "name": "second_checklist_answer",
                    "value": "second_checklist_answer",
                    "classifications": []
                  }
                ]
              },
              {
                "feature_id": "cluu14r3p0ou3148p6d15q82b",
                "feature_schema_id": "cluu14fnh01fe0703abp5fjgx",
                "name": "radio_convo",
                "value": "radio_convo",
                "message_id": "0",
                "conversational_radio_answer": {
                  "feature_id": "cluu14r3p0ou4148pc028jtzk",
                  "feature_schema_id": "cluu14fnh01ff070383rh4ryk",
                  "name": "first_radio_answer",
                  "value": "first_radio_answer",
                  "classifications": []
                }
              },
              {
                "feature_id": "cluu14r3p0ou5148piuv74m17",
                "feature_schema_id": "cluu14fni01fs0703ax77277l",
                "name": "nested_radio_question",
                "value": "nested_radio_question",
                "radio_answer": {
                  "feature_id": "cluu14r3p0ou6148p0b4azzcu",
                  "feature_schema_id": "cluu14fni01ft07033xic99k3",
                  "name": "first_radio_answer",
                  "value": "first_radio_answer",
                  "classifications": [
                    {
                      "feature_id": "cluu14r3p0ou7148pgmcqsf11",
                      "feature_schema_id": "cluu14fni01fu0703c3iu2c0a",
                      "name": "sub_radio_question",
                      "value": "sub_radio_question",
                      "radio_answer": {
                        "feature_id": "cluu14r3p0ou8148pka3hvx26",
                        "feature_schema_id": "cluu14fni01fv07031r8i190o",
                        "name": "first_sub_radio_answer",
                        "value": "first_sub_radio_answer",
                        "classifications": []
                      }
                    }
                  ]
                }
              },
              {
                "feature_id": "cluu14r3p0ou9148puacr13og",
                "feature_schema_id": "cluu14fni01fk07033aeye6ht",
                "name": "nested_checklist_question",
                "value": "nested_checklist_question",
                "message_id": "10",
                "conversational_checklist_answers": [
                  {
                    "feature_id": "cluu14r3p0oua148pttkqa3fe",
                    "feature_schema_id": "cluu14fni01fl0703eg9y2qgt",
                    "name": "first_checklist_answer",
                    "value": "first_checklist_answer",
                    "classifications": [
                      {
                        "feature_id": "cluu14r3p0oub148p3hld5bh9",
                        "feature_schema_id": "cluu14fni01fm0703b3mwa6ot",
                        "name": "sub_checklist_question",
                        "value": "sub_checklist_question",
                        "checklist_answers": [
                          {
                            "feature_id": "cluu14r3p0ouc148pfpiwlzht",
                            "feature_schema_id": "cluu14fni01fn0703apfk8j9q",
                            "name": "first_sub_checklist_answer",
                            "value": "first_sub_checklist_answer",
                            "classifications": []
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ],
            "relationships": []
          }
        }
      ],
      "project_details": {
        "ontology_id": "cluu14fmp01f307039z1h2c64",
        "task_name": "Done",
        "batch_id": "04e9d4c0-f758-11ee-8be6-db43b18899b6",
        "batch_name": "first-batch-convo-demo",
        "workflow_status": "DONE",
        "priority": 5,
        "consensus_expected_label_count": 1,
        "workflow_history": []
      }
    }
  }
}

Sample model run export

{
  "data_row": {
    "id": "clfbnskoxb9q9076fbyjngwhm",
    "global_key": "conversation-1.json",
    "row_data": "https://storage.googleapis.com/labelbox-developer-testing-assets/conversational_text/1000-conversations/conversation-1.json",
    "details": {
      "dataset_id": "clfbnsjaj05hr07z605db0w3b",
      "dataset_name": "conversational_annotation_import_demo_dataset",
      "created_at": "2023-03-16T22:04:33.000+00:00",
      "updated_at": "2024-01-18T19:10:53.352+00:00",
      "created_by": "[email protected]"
    }
  },
  "media_attributes": {
    "mime_type": "application/vnd.labelbox.conversational",
    "labelable_ids": [
      "0",
      "2",
      "4",
      "6",
      "8",
      "10",
      "12",
      "14",
      "16",
      "18"
    ],
    "message_count": 20
  },
  "attachments": [],
  "metadata_fields": [],
  "experiments": {
    "a3143b06-742d-0576-d722-c187a5aad1b3": {
      "name": "Conversational_model_run_9985d371-1b0b-4a5b-8c94-4a6167b20090",
      "runs": {
        "a3143b06-adc7-086f-79a5-d251a0054cb8": {
          "name": "iteration 1",
          "run_data_row_id": "4f22e94f-71da-45ac-bab7-f95daf04e7a1",
          "labels": [
            {
              "label_kind": "Default",
              "version": "1.0.0",
              "id": "clq10ymdubt0u1447v6s77glu",
              "annotations": {
                "objects": [
                  {
                    "feature_id": "e063fe4e-4675-0988-9f81-659c83dd1b43",
                    "feature_schema_id": "clq10ybnl067t07ztbavefdsy",
                    "name": "ner",
                    "value": "ner",
                    "annotation_kind": "ConversationalTextEntity",
                    "classifications": [],
                    "conversational_location": {
                      "message_id": "4",
                      "location": {
                        "start": 0,
                        "end": 8
                      }
                    }
                  }
                ],
                "classifications": [
                  {
                    "feature_id": "169f1fee-5db4-02c9-a232-dfb245a158ec",
                    "feature_schema_id": "clq10ybnl068907ztf1htgtoc",
                    "name": "nested_checklist_question",
                    "value": "nested_checklist_question",
                    "message_id": "10",
                    "conversational_checklist_answers": [
                      {
                        "feature_id": "c1c5898b-f1ce-02c7-b806-930ac8140923",
                        "feature_schema_id": "clq10ybnl068a07ztcnyzbhsn",
                        "name": "first_checklist_answer",
                        "value": "first_checklist_answer",
                        "classifications": [
                          {
                            "feature_id": "1fc2b7e8-a292-02ad-81b6-10cb9bdd56c4",
                            "feature_schema_id": "clq10ybnl068b07zth87h8c34",
                            "name": "sub_checklist_question",
                            "value": "sub_checklist_question",
                            "checklist_answers": [
                              {
                                "feature_id": "de42a672-041f-03f3-bbd9-e771e332030a",
                                "feature_schema_id": "clq10ybnm068c07zt53sdcs0m",
                                "name": "first_sub_checklist_answer",
                                "value": "first_sub_checklist_answer",
                                "classifications": []
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "feature_id": "8adc0320-6d61-0011-bda0-80842b3733da",
                    "feature_schema_id": "clq10ybnm068h07ztaugh4uma",
                    "name": "nested_radio_question",
                    "value": "nested_radio_question",
                    "radio_answer": {
                      "feature_id": "475fb394-f606-0223-b625-48045ebf7208",
                      "feature_schema_id": "clq10ybnm068i07zt1xxv25it",
                      "name": "first_radio_answer",
                      "value": "first_radio_answer",
                      "classifications": [
                        {
                          "feature_id": "a61d83fd-4c47-0e88-9ae1-da3eb100eea0",
                          "feature_schema_id": "clq10ybnm068j07ztcqf794w4",
                          "name": "sub_radio_question",
                          "value": "sub_radio_question",
                          "radio_answer": {
                            "feature_id": "6dbde4c3-3a1e-0348-a5ac-7787a8ac0461",
                            "feature_schema_id": "clq10ybnm068k07ztdx9dca3i",
                            "name": "first_sub_radio_answer",
                            "value": "first_sub_radio_answer",
                            "classifications": []
                          }
                        }
                      ]
                    }
                  },
                  {
                    "feature_id": "96dce41f-f1c1-0822-9848-39c098b449f5",
                    "feature_schema_id": "clq10ybnl067v07ztb8f91r4u",
                    "name": "text_convo",
                    "value": "text_convo",
                    "message_id": "0",
                    "conversational_text_answer": {
                      "content": "the answer to the text questions are right here"
                    }
                  },
                  {
                    "feature_id": "ba7c519c-c618-01ba-ac4b-fdbbd8137bf0",
                    "feature_schema_id": "clq10ybnl068307ztd255hndf",
                    "name": "radio_convo",
                    "value": "radio_convo",
                    "message_id": "0",
                    "conversational_radio_answer": {
                      "feature_id": "ec0fc3fb-1948-0ff9-8bc6-0377721e4f0e",
                      "feature_schema_id": "clq10ybnl068407zt1x572rym",
                      "name": "first_radio_answer",
                      "value": "first_radio_answer",
                      "classifications": []
                    }
                  },
                  {
                    "feature_id": "fe3a901b-8e62-01fe-a792-10b15ec7fa0d",
                    "feature_schema_id": "clq10ybnl067x07zt0u67b9h3",
                    "name": "checklist_convo",
                    "value": "checklist_convo",
                    "message_id": "2",
                    "conversational_checklist_answers": [
                      {
                        "feature_id": "699a5673-bb4a-06d3-9b9e-19237e11f96d",
                        "feature_schema_id": "clq10ybnl068007zt6ct25775",
                        "name": "second_checklist_answer",
                        "value": "second_checklist_answer",
                        "classifications": []
                      },
                      {
                        "feature_id": "da192bd6-84ec-0acf-b875-d1ade525f466",
                        "feature_schema_id": "clq10ybnl067y07zt6gvjczsg",
                        "name": "first_checklist_answer",
                        "value": "first_checklist_answer",
                        "classifications": []
                      }
                    ]
                  }
                ],
                "relationships": []
              }
            }
          ],
          "predictions": [
            {
              "label_kind": "Default",
              "version": "1.0.0",
              "id": "clq10ymdubt0u1447v6s77glu",
              "annotations": {
                "objects": [
                  {
                    "feature_id": "9c8f89a7-7211-4b33-a3c5-a3dab59f0407",
                    "feature_schema_id": "clq10ybnl067t07ztbavefdsy",
                    "name": "ner",
                    "value": "ner",
                    "annotation_kind": "ConversationalTextEntity",
                    "classifications": [],
                    "conversational_location": {
                      "message_id": "4",
                      "location": {
                        "start": 0,
                        "end": 8
                      }
                    }
                  }
                ],
                "classifications": [
                  {
                    "feature_id": "20cda99c-d0f7-4e59-8f43-a8b4f3929e2f",
                    "feature_schema_id": "clq10ybnl068307ztd255hndf",
                    "name": "radio_convo",
                    "value": "radio_convo",
                    "message_id": "0",
                    "conversational_radio_answer": {
                      "feature_id": "ec1ec509-79b6-48e7-973c-9c06e754630f",
                      "feature_schema_id": "clq10ybnl068407zt1x572rym",
                      "name": "first_radio_answer",
                      "value": "first_radio_answer",
                      "classifications": []
                    }
                  },
                  {
                    "feature_id": "49e4667e-ed14-400b-9b75-b8b89bfb6f11",
                    "feature_schema_id": "clq10ybnm068h07ztaugh4uma",
                    "name": "nested_radio_question",
                    "value": "nested_radio_question",
                    "radio_answer": {
                      "feature_id": "723be4ec-fa0c-4a67-9df0-a18f56f7bbd8",
                      "feature_schema_id": "clq10ybnm068i07zt1xxv25it",
                      "name": "first_radio_answer",
                      "value": "first_radio_answer",
                      "classifications": [
                        {
                          "feature_id": "f28f3d0a-9428-4b45-8de1-4ec6714da726",
                          "feature_schema_id": "clq10ybnm068j07ztcqf794w4",
                          "name": "sub_radio_question",
                          "value": "sub_radio_question",
                          "radio_answer": {
                            "feature_id": "82808a1e-a004-4965-bb77-4ab9e499c747",
                            "feature_schema_id": "clq10ybnm068k07ztdx9dca3i",
                            "name": "first_sub_radio_answer",
                            "value": "first_sub_radio_answer",
                            "classifications": []
                          }
                        }
                      ]
                    }
                  },
                  {
                    "feature_id": "988e5b9a-9a6d-4338-96bf-901475b4a2c0",
                    "feature_schema_id": "clq10ybnl068907ztf1htgtoc",
                    "name": "nested_checklist_question",
                    "value": "nested_checklist_question",
                    "message_id": "10",
                    "conversational_checklist_answers": [
                      {
                        "feature_id": "9ea5984d-fb21-48e4-96c8-ce19162b5850",
                        "feature_schema_id": "clq10ybnl068a07ztcnyzbhsn",
                        "name": "first_checklist_answer",
                        "value": "first_checklist_answer",
                        "classifications": [
                          {
                            "feature_id": "bf896185-5a77-410e-a4cd-abf0b07122fa",
                            "feature_schema_id": "clq10ybnl068b07zth87h8c34",
                            "name": "sub_checklist_question",
                            "value": "sub_checklist_question",
                            "checklist_answers": [
                              {
                                "feature_id": "0812ee3d-7f5d-480b-82a2-4e965a48fc49",
                                "feature_schema_id": "clq10ybnm068c07zt53sdcs0m",
                                "name": "first_sub_checklist_answer",
                                "value": "first_sub_checklist_answer",
                                "classifications": []
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "feature_id": "cb4730df-2e22-45db-bc74-fd439d577571",
                    "feature_schema_id": "clq10ybnl067x07zt0u67b9h3",
                    "name": "checklist_convo",
                    "value": "checklist_convo",
                    "message_id": "2",
                    "conversational_checklist_answers": [
                      {
                        "feature_id": "8184feca-970c-4ba7-bfbd-4d0eb5849a90",
                        "feature_schema_id": "clq10ybnl068007zt6ct25775",
                        "name": "second_checklist_answer",
                        "value": "second_checklist_answer",
                        "classifications": []
                      },
                      {
                        "feature_id": "dc40cfef-aa6f-436d-a5b5-0d56bbd1741e",
                        "feature_schema_id": "clq10ybnl067y07zt6gvjczsg",
                        "name": "first_checklist_answer",
                        "value": "first_checklist_answer",
                        "classifications": []
                      }
                    ]
                  },
                  {
                    "feature_id": "db7109ed-e380-4389-ab2f-98e72b4c2afe",
                    "feature_schema_id": "clq10ybnl067v07ztb8f91r4u",
                    "name": "text_convo",
                    "value": "text_convo",
                    "message_id": "0",
                    "conversational_text_answer": {
                      "content": "the answer to the text questions are right here"
                    }
                  }
                ],
                "relationships": []
              }
            }
          ]
        }
      }
    }
  },
  "models": {}
}