Overview

The Verbit Insights API provides access to insight data generated by the Verbit AI engine known as Gen V. It supports insights for both live sessions and post-production jobs. This data can range from anything like a summary, keyword terms or even the generated quizzes from a live session.

Authentication

All Verbit APIs use OAuth2.0 authentication. This will require a bearer token to be generated and passed through the Authorization header.Refer to the documentation for details on how to get an API token.

Workflow

Insights start generating after the first request and are updated at intervals based on the type of insight.

Live Sessions - Insights are generated in real-time, every few minutes until the session ends. The user should poll for updates periodically.
Post-Production Jobs - These are files that were uploaded with captions and transcription already processed. Insights are generated after transcription is completed and job_status will always befinished.

Learn more how to request the generated insight API data here in the API Reference.

Get Generated Insights

The user will need to pass an id to get insight data for a specific order or job. Each id has it's own assigned query parameter:

job_id - The user will need to pass this id in this parameter for post-production job files .
order_id - The user will need to pass the order_id in this parameter from a live session.

For example, if someone needed the insights of a post-production file, they would pass the following call (to obtain these ids the user can make a call to List Order API endpoint):

curl --request GET \
     --url 'https://ai.verbit.co/api/v2/insights?job_id=12345' \
     --header 'accept: application/json' \
     --header 'Authorization: bearer <bearer-token>

The response from this call would return your all the insight data for the job id "12345":

{
  "insights": {
    "quiz": {
      "data": [
        {
          "uuid": "c36d9a9d-5714-412c-a266-efca8e293042",
          "id": 1,
          "question": "What can the atmosphere of an exoplanet reveal?",
          "answers": {
            "A": "Only the planet's color",
            "B": "A wealth of information including temperature, air pressure, and suitability for life",
            "C": "The age of the planet",
            "D": "The planet's mass"
          },
          "correct_answer": "B"
        },
        {
          "uuid": "a227fd49-a53d-4ffe-bf3e-4de009dbc76b",
          "id": 2,
          "question": "How do astronomers study exoplanet atmospheres?",
          "answers": {
            "A": "By monitoring the host star's light during a transit",
            "B": "By directly imaging the exoplanet",
            "C": "By sending probes to the exoplanet",
            "D": "By analyzing radio waves from the exoplanet"
          },
          "correct_answer": "A"
        },
        {
          "uuid": "595291f4-5d67-4d28-989e-c583451bf07b",
          "id": 3,
          "question": "What happens to starlight during an exoplanet transit?",
          "answers": {
            "A": "A tiny fraction passes through the planet's atmosphere and interacts with chemical elements",
            "B": "All of the starlight is blocked",
            "C": "The starlight increases in intensity",
            "D": "The starlight changes color"
          },
          "correct_answer": "A"
        },
        {
          "uuid": "f5741fba-f0ef-4cf4-8c2b-6a91850b4bb2",
          "id": 4,
          "question": "What are absorption lines in a spectrum?",
          "answers": {
            "A": "Lines showing the planet's rotation speed",
            "B": "Bright lines indicating the presence of certain gases",
            "C": "Distinctive dark lines that act as chemical fingerprints of elements in the atmosphere",
            "D": "Indicators of the planet's magnetic field strength"
          },
          "correct_answer": "C"
        },
        {
          "uuid": "877008ae-8a38-42b0-bac5-18ab9c4c87bd",
          "id": 5,
          "question": "Why is studying exoplanet atmospheres challenging?",
          "answers": {
            "A": "Exoplanets are too small to be seen",
            "B": "Exoplanets are too far away to study",
            "C": "Only a tiny fraction of the star's light interacts with the exoplanet's atmosphere",
            "D": "Earth's atmosphere interferes with observations"
          },
          "correct_answer": "C"
        },
        {
          "uuid": "136676ca-6d68-4130-9792-f78d4ddd8252",
          "id": 6,
          "question": "Which telescope is mentioned as being powerful enough to study exoplanet atmospheres?",
          "answers": {
            "A": "Hubble Space Telescope",
            "B": "James Webb Space Telescope",
            "C": "Keck Observatory",
            "D": "Very Large Telescope"
          },
          "correct_answer": "A"
        },
        {
          "uuid": "d88ab2a5-f7a2-4cd0-bd3a-a9a801cd6bab",
          "id": 7,
          "question": "What range of spectra can Hubble collect?",
          "answers": {
            "A": "Only visible light",
            "B": "From ultraviolet through optical to near-infrared",
            "C": "Only X-rays",
            "D": "Only radio waves"
          },
          "correct_answer": "B"
        },
        {
          "uuid": "154ea01d-0a62-4114-bb49-023de074f0ad",
          "id": 8,
          "question": "What limitation does Hubble face in studying exoplanet atmospheres?",
          "answers": {
            "A": "It can only detect the strongest lines from an atmosphere in a given spectrum",
            "B": "It cannot detect any atmospheric components",
            "C": "It can only study gaseous planets",
            "D": "It can only study Earth-like planets"
          },
          "correct_answer": "A"
        },
        {
          "uuid": "0d25f0c0-7577-4dca-83dc-d5cc4e7ce724",
          "id": 9,
          "question": "What is needed to detect weaker signatures in atmospheric spectra?",
          "answers": {
            "A": "Bigger and more sensitive instruments",
            "B": "More observation time with Hubble",
            "C": "Ground-based telescopes",
            "D": "Better data analysis techniques"
          },
          "correct_answer": "A"
        },
        {
          "uuid": "93f47080-169b-453d-b220-9cba5aa09f14",
          "id": 10,
          "question": "Which future telescope is mentioned that will help advance exoplanet atmosphere studies?",
          "answers": {
            "A": "Thirty Meter Telescope",
            "B": "Extremely Large Telescope",
            "C": "James Webb Space Telescope",
            "D": "Giant Magellan Telescope"
          },
          "correct_answer": "C"
        }
      ],
      "updated_at": "2024-10-03T18:45:31.064743Z",
      "status": {
        "name": "ok",
        "quota": 0.992435,
        "message": ""
      }
    },
    "title": {
      "data": [
        {
          "text": "Unveiling the Mysteries of Exoplanet Atmospheres: Challenges and Advancements"
        }
      ],
      "updated_at": "2024-10-03T18:45:16.099574Z",
      "status": {
        "name": "ok",
        "quota": 0.996645,
        "message": ""
      }
    },
    "summary": {
      "data": [
        {
          "title": "Studying Exoplanet Atmospheres",
          "text": "Exoplanets fascinate astronomers and the public alike, with questions about their appearance, habitability, and potential for life. Studying exoplanet atmospheres is crucial for understanding these distant worlds, but it's a challenging task due to their small size and lack of light emission. Astronomers use the transit method, observing the host star's light as it passes through the exoplanet's atmosphere during a transit. This creates absorption lines in the star's spectrum, revealing the atmosphere's composition. The Hubble Space Telescope has been instrumental in these studies, but it can only detect the strongest atmospheric signatures. The upcoming James Webb Space Telescope is expected to provide more sensitive instruments for detecting weaker atmospheric signatures, advancing our understanding of exoplanet atmospheres."
        }
      ],
      "updated_at": "2024-10-11T17:06:00.786423Z",
      "status": {
        "name": "ok",
        "quota": 0.99369,
        "message": ""
      }
    },
    "keywords": {
      "data": [
        {
          "uuid": "bd36ca17-c49f-4571-87e1-be69dd506f39",
          "text": "exoplanets"
        },
        {
          "uuid": "93f1d13f-053b-4cf4-b85e-4c57a82d12e4",
          "text": "atmospheres"
        },
        {
          "uuid": "45442ad2-b20e-4ff5-82dc-124fccb839e5",
          "text": "astronomy"
        },
        {
          "uuid": "7cead69e-e056-4a83-a790-6517d9d5ca59",
          "text": "spectroscopy"
        },
        {
          "uuid": "d817e114-24ce-4b41-b9f2-98f97a204bae",
          "text": "telescopes"
        },
        {
          "uuid": "670bd15f-3208-4e59-9983-0e5c1a631f01",
          "text": "Hubble"
        },
        {
          "uuid": "24c9a54f-4727-4663-947d-f41605fac449",
          "text": "James Webb Space Telescope"
        },
        {
          "uuid": "2796d2c7-6a7d-4c93-8fff-04a0eb736c8d",
          "text": "chemical composition"
        },
        {
          "uuid": "802975e0-2ddd-4af2-ba44-14e4419d844b",
          "text": "transits"
        },
        {
          "uuid": "e8436538-6b37-4143-9866-1db04e7e510b",
          "text": "life"
        }
      ],
      "updated_at": "2024-10-11T17:06:02.680352Z",
      "status": {
        "name": "ok",
        "quota": 0.994205,
        "message": ""
      }
    },
    "chapters": {
      "data": [
        {
          "title": "Introduction to Exoplanets",
          "timestamp": "00:00:01",
          "summary": [
            "Exoplanets fascinate astronomers and the public",
            "Questions about their appearance, habitability, and potential for life",
            "Importance of studying exoplanet atmospheres",
            "Challenges in detecting and studying exoplanet atmospheres"
          ],
          "uuid": "07e317ff-5f85-4faa-a714-a620fa40405e"
        },
        {
          "title": "Studying Exoplanet Atmospheres",
          "timestamp": "00:01:11",
          "summary": [
            "Observing exoplanet transits to study atmospheres",
            "Light passing through atmosphere interacts with chemical elements",
            "Absorption lines in star's spectrum reveal atmospheric composition",
            "Challenges in detecting weak absorption lines"
          ],
          "uuid": "89a7f6a8-3a00-437d-b730-c8e211971432"
        },
        {
          "title": "Hubble's Role in Exoplanet Research",
          "timestamp": "00:02:34",
          "summary": [
            "Hubble's capabilities in studying exoplanet atmospheres",
            "Instruments for collecting spectra from UV to near-infrared",
            "Limitations in detecting fine details of atmospheres",
            "Need for more sensitive instruments for future research"
          ],
          "uuid": "becc0bf2-c412-4e08-b448-22e1a920ef94"
        },
        {
          "title": "Future of Exoplanet Atmosphere Studies",
          "timestamp": "00:03:26",
          "summary": [
            "Hubble's continued contribution to understanding planetary atmospheres",
            "Need for bigger and more sensitive instruments",
            "Introduction of the James Webb Space Telescope",
            "Expectations for advancing exoplanet atmosphere research"
          ],
          "uuid": "75b7118d-74ba-4578-8ed2-ba95578e76a6"
        }
      ],
      "updated_at": "2024-10-03T18:45:22.095716Z",
      "status": {
        "name": "ok",
        "quota": 0.9953,
        "message": ""
      }
    }
  },
  "job_status": "finished",
  "process_status": "completed"
}

insight_name - The insight name allows the user to select specific insight data type. If the insight_name parameter is not used, then all insights will be retrieved by default. Here is a list of all the insights that can be used in the insight_name parameter:
- Chapters
- Document
- Inconsistencies
- Keywords
- Person
- Place
- Quiz
- Summary
- Title

When selecting a specific insight it would be added to the following query, for example, if someone wanted specifically the summary from a post production file:

curl --request GET \
     --url 'https://ai.verbit.co/api/v2/insights?job_id=12345&insight_name=summary' \
     --header 'accept: application/json' \
     --header 'Authorization: bearer <bearer-token>

Only the summary data for job id "12345" will now be returned:

{
  "insights": {
    "summary": {
      "data": [
        {
          "title": "Studying Exoplanet Atmospheres",
          "text": "Exoplanets fascinate astronomers and the public alike, with questions about their appearance, habitability, and potential for life. Studying exoplanet atmospheres is crucial for understanding these distant worlds, but it's a challenging task due to their small size and lack of light emission. Astronomers use the transit method, observing the host star's light as it passes through the exoplanet's atmosphere during a transit. This creates absorption lines in the star's spectrum, revealing the atmosphere's composition. The Hubble Space Telescope has been instrumental in these studies, but it can only detect the strongest atmospheric signatures. The upcoming James Webb Space Telescope is expected to provide more sensitive instruments for detecting weaker atmospheric signatures, advancing our understanding of exoplanet atmospheres."
        }
      ],
      "updated_at": "2024-10-11T17:06:00.786423Z",
      "status": {
        "name": "ok",
        "quota": 0.99369,
        "message": ""
      }
    }
  },
  "job_status": "finished",
  "process_status": "completed"
}

Response Statuses Overview

Each insight status key in the response contains a value object with the following fields:

name- The name object contains two values:
- insufficient_data- This status value will display if the insights are not generated.
- ok- This status value will display when insights are available.
quota- This key value shows the remaining quota as a percentage of the limit per insight type (range: 0 to 1).
message - This key value may contain additional information or descriptions.

{
  "status": {
        "name": "ok",
        "quota": 0.99369,
        "message": ""
     }
  }
}

job_status: This key value Indicates the current status of the job is running or finished.
process_status: This key value Indicates the insights generation status with the following values:
- ready: Generation is available and ready to start for the job.
- generating: Insights are presently being generated.
- complete: Insights generation is finished.

{
  "job_status": "finished",
  "process_status": "completed"
}

Example Responses

For `place` insight types:

{
  "insights": {
    "places": {
      "data": [
        {
          "uuid": "f7b1b2b0-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
          "text": "place1",
          "timestamp": "00:12:03.000"
        },
        {
          "uuid": "abababab-1b1b-4b1b-8b1b-ffffffffffff",
          "text": "place2",
          "timestamp": "00:14:03.000"
        }
      ],
      "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
      },
      "updated_at": "2019-01-01T00:00:00Z"
    }
  },
  "job_status": "running",
  "process_status": "ready"
}

For `document` insight types:

{
  "insights": {
    "documents": {
      "data": [
        {
          "uuid": "ccccccccc-1b1b-4b1b-8b1b-bbbbbbbbbbbbb",
          "text": "document1",
          "timestamp": "00:12:03.000"
        }
      ],
      "status": {
        "name": "insufficient_data",
        "quota": 1,
        "message": "Insufficient data"
      },
      "updated_at": "2019-01-01T00:00:00Z"
    }
  },
  "job_status": "running",
  "process_status": "ready"
}

For `person` insight types:

{
  "insights": {
    "people": {
      "data": [
        {
          "uuid": "f7b1b2b0-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
          "text": "person1",
          "timestamp": "00:12:03.000"
        },
        {
          "uuid": "abababab-1b1b-4b1b-8b1b-ffffffffffff",
          "text": "person2",
          "timestamp": "00:14:03.000"
        }
      ],
      "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
      },
      "updated_at": "2019-01-01T00:00:00Z"
    }
  },
  "job_status": "running",
  "process_status": "ready"
}

For `quiz` insight types:

{
  "insights": {
    "quiz": {
      "data": [
        {
          "uuid": "f7b1b2b0-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
          "id": "1",
          "question": "how much wood could a woodchuck chuck id a woodchuck would have wood",
          "answers": {
            "A": "7",
            "B": "21",
            "C": "0",
            "D": "9000"
          },
          "correct_answer": "D",
          "timestamp": "00:12:03.000"
        },
        {
          "uuid": "7b1b2b0-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
          "id": "2",
          "question": "If two witches were watching two watches, which witch would watch which watch?",
          "answers": {
            "A": "They are asleep",
            "B": "Every witch would watch all of them",
            "C": "First whitch Second watch",
            "D": "Second witch first watch"
          },
          "correct_answer": "B",
          "timestamp": "00:12:03.000"
        }
      ],
      "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
      },
      "updated_at": "2019-01-01T00:00:00Z"
    }
  },
  "job_status": "running",
  "process_status": "ready"
}

For `summary` insight types:

{
"insights": {
    "summary": {
    "data": [
        {
        "title": "this is a optional title",
        "text": "this is a summary"
        }
    ],
    "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
    },
    "updated_at": "2019-01-01T00:00:00Z"
    }
},
"job_status": "running",
"process_status": "ready"
}

For `title` insight types:

{
  "insights": {
    "title": {
      "data": [
        {
          "text": "this is a title"
        }
      ],
      "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
      },
      "updated_at": "2019-01-01T00:00:00Z"
    }
  },
  "job_status": "running",
  "process_status": "ready"
}

For `keywords` insight types:

{
  "insights": {
    "keywords": {
      "data": [
        {
          "uuid": "ccccccccc-1b1b-4b1b-8b1b-bbbbbbbbbbbbb",
          "text": "keyward1"
        },
        {
          "uuid": "aaaaaaaa-1b1b-4b1b-8b1b-bbbbbbbbbbbbb",
          "text": "keyward2"
        }
      ],
      "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
      },
      "updated_at": "2019-01-01T00:00:00Z"
    }
  },
  "job_status": "running",
  "process_status": "ready"
}

For `chapters` insight types:

{
"insights": {
    "chapters": {
    "data": [
        {
        "uuid": "f7b1b2b0-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
        "title": "A Chapter",
        "summary": [
            "Summary of the chapter",
            "another bullet point"
        ],
        "timestamp": "00:12:03.000"
        },
        {
        "uuid": "7b1b2b0-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
        "title": "Another chapter",
        "summary": [
            "Summary of another chapter",
            "next bullet summary"
        ],
        "timestamp": "00:12:03.000"
        }
    ],
    "status": {
        "name": "ok",
        "quota": 0.7,
        "message": ""
    },
    "updated_at": "2019-01-01T00:00:00Z"
    }
},
"job_status": "running",
"process_status": "ready"
}

Overview

Authentication

Workflow

Get Generated Insights

Response Statuses Overview

Example Responses

For place insight types:

For document insight types:

For person insight types:

For quiz insight types:

For summary insight types:

For title insight types:

For keywords insight types:

For chapters insight types: