Get Protocol by Slug

The getProtocolBySlug query allows you to retrieve the current state, metadata, speakers, and summaries of an existing protocol.

This query is used to:

• check the current creating step of the protocol,
• check whether the protocol has finished processing,
• retrieve speaker information,
• retrieve summary text and
• use this information for the renameSpeakerInTextsegment mutation.

Understanding the status Field

Every protocol includes a boolean status field:

• status = false → processing is still running
• status = true → processing is finished, and all final data is available

Use this field to determine whether your application should:

• show a loading/progress screen, or
• continue to the next step

GraphQL Query

fragment protocolDetails on ApiProtocolType {
  slug
  name
  status
  date
  language
  empty
  creatingStep
  creatingStepList
  renamedSpeakers
}

fragment speakerDetails on ApiSpeakerType {
  slug
  gender
  familyName
  givenName
  party
  preTitle
  postTitle
  posShort
  posLong
  systemId
}

fragment summaryPerSpeakerDetails on ApiSummaryPerSpeakerItemTypeWithSpeaker {
  speakerObj {
    ...speakerDetails
  }
  textList
  speakerSuggestion
}

query GetProtocolBySlug($protocolSlug: String!) {
  getProtocolBySlug(protocolSlug: $protocolSlug) {
    serverLoad
    protocol {
      ...protocolDetails
    }
    speakerList
    summaryPerSpeakerList {
      ...summaryPerSpeakerDetails
    }
    attendees{
      ...speakerDetails
    }
  }
}

New Fields: serverLoad and creatingStepList

serverLoad — Returns the current queue load at the time of the request:

Use this to inform users about expected processing delays.

creatingStepList — A chronological list of all processing steps completed up to the current one. Useful for building a progress indicator in your UI:

["Dateiverarbeitung gestartet", "Protokoll wird vorbereitet", "Transkription begonnen", ...]

The currently active step is also available as the single creatingStep field.

Example JS Code

Below is a minimal example showing how to fetch the protocol and check whether it’s finished processing:

import axios from "axios";

export const GET_PROTOCOL_BY_SLUG = `
  fragment protocolDetails on ApiProtocolType {
    slug
    name
    status
    date
    language
    empty
    creatingStep
    creatingStepList
    renamedSpeakers
  }

  fragment speakerDetails on ApiSpeakerType {
    slug
    gender
    familyName
    givenName
    party
    preTitle
    postTitle
    posShort
    posLong
    systemId
  }

  fragment summaryPerSpeakerDetails on ApiSummaryPerSpeakerItemTypeWithSpeaker {
    speakerObj {
      ...speakerDetails
    }
    textList
    speakerSuggestion
  }

  query GetProtocolBySlug($protocolSlug: String!) {
    getProtocolBySlug(protocolSlug: $protocolSlug) {
      serverLoad
      protocol {
        ...protocolDetails
      }
      speakerList
      summaryPerSpeakerList {
        ...summaryPerSpeakerDetails
      }
      attendees{
        ...speakerDetails
      }
    }
  }
`;

const fetchProtocol = async (protocolSlug) => {
  try {
    const response = await axios({
      method: "POST",
      url: "https://api-v2.speechmind.com/external/v2/graphql",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.SPEECHMIND_API_KEY,
      },
      data: JSON.stringify({
        query: GET_PROTOCOL_BY_SLUG,
        variables: { protocolSlug },
      }),
    });

    const data = response.data.data.getProtocolBySlug;

    console.log("Server load:", data.serverLoad);
    console.log("Protocol:", data.protocol);
    console.log("Creating steps:", data.protocol.creatingStepList);
    console.log("Speakers:", data.speakerList);
    console.log("Summary per speaker:", data.summaryPerSpeakerList);
    console.log("Attendees:", data.attendees);

    if (data.protocol.status === true) {
      console.log("✔️ Processing completed!");
    } else {
      console.log("⏳ Still processing...");
    }
  } catch (error) {
    console.error("Error fetching protocol:", error);
  }
};

fetchProtocol("your-protocol-slug");

Using speakerList & summaryPerSpeakerList for Renaming Speakers

Once your protocol has finished processing (status = true), the speakerList and summaryPerSpeakerList provide the structured data you need to identify and rename speakers in your text segments.

1. Understanding the Data

• speakerList — Contains all speakers along with their spoken segments and timing information:

{
  "SPEAKER_SLUG": {
    "duration": 61.05,
    "textsegment": [
      { "id": 328124, "time": { "start_time": 13.2, "end_time": 18.88 }, "text": "…", "textsegment_duration": 5.68 }
    ],
    "speaker_obj": {
      "slug": "SPEAKER_SLUG",
      "givenName": "Thomas",
      "familyName": "Müller",
      "preTitle": "",
      "postTitle": "",
      "gender": "m"
    }
  }
}

• attendees — The list of speakers passed via initProtocol.

• summaryPerSpeakerList — Provides aggregated summaries and suggested names for each speaker:

[
  {
    "speakerObj": {
      "slug": "SPEAKER_SLUG",
      "givenName": "Thomas",
      "familyName": "Müller"
    },
    "textList": "{\"0\": [\"Summary text...\"]}",
    "speakerSuggestion": "[\"Herr Müller\"]"
  }
]

2. Preparing for renameSpeakerInTextsegment

You can use these objects to:

• Map speaker slugs to their current givenName / familyName
• Determine suggested names from speakerSuggestion
• use speakerList.textsegment list for passing the user the audio time for listening to a current audio position and the text to identify the speaker by voice or text
• summaryPerSpeakerList.speakerSuggestion provides AI generated suggestions who this speaker is based on the audio data

3. Example flow

// Example: Build mapping for renaming
const speakerMap = {};
Object.values(data.speakerList).forEach(speakerItem => {
  speakerMap[speakerItem.speaker_obj.slug] = {
    currentName: `${speakerItem.speaker_obj.givenName} ${speakerItem.speaker_obj.familyName}`,
    suggestedNames: []
  };
});

// Fill suggested names from summary
data.summaryPerSpeakerList.forEach(summaryItem => {
  const slug = summaryItem.speakerObj.slug;
  if (speakerMap[slug]) {
    speakerMap[slug].suggestedNames = JSON.parse(summaryItem.speakerSuggestion);
  }
});

console.log("Speaker rename mapping:", speakerMap);

4. Next step

Once you have your speakerMap, you can call the renameSpeakerInTextsegment mutation.