Guide · async

Search your transcriptions

Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.

GET /v1/transcriptions takes the same filters as the dashboard's search: give any of them and every one must match. The server filters before it pages, so total is the number of matches and nextCursor pages through matches only.

1. Filter the list

   Parameter	Keeps
   q	Every word in the name, the source's name or its link, in any case: q=team meeting
   site	Links from that site, by its id: youtube, vimeo, loom, soundcloud, twitch…
   language	That spoken language, set or detected: en, es…
   kind	file (an upload), link (a URL) or live (a microphone or a stream)
   tag	That tag, by its id or its name (tags.list)
   origin	Where it was made: dashboard, api, extension…
   broadcast	The live transcriptions feeding that broadcast, by its id
   createdAfter, createdBefore	An RFC 3339 time, or a YYYY-MM-DD date for the whole day (UTC)
   lifecycle	active (the default), archived or all

   GET /v1/transcriptions?q=interview&site=youtube&language=en&createdAfter=2026-01-01 is every English YouTube interview made this year. A value that does not parse (a kind of video, a date of yesterday) is 400 invalid_options. In the SDKs, list() reads every page of matches and listPage() reads one.

2. Keep the shared ones

   shared=true keeps the transcriptions with a live share link, and each one carries shareCode, the code of its newest link. shared=false keeps those with none. A transcription gets a share link when it is created with shareLink: true, from the dashboard's Share button, or from POST /v1/transcriptions/{id}/share-links. A revoked link no longer counts.

3. Play them

   A share code plays in the open-source @vocalstack/player with no key, so the page that lists your videos needs no credential. Call the API on your server, where the API key stays, and send the page only the codes:

   import { VocalStackPlayer } from '@vocalstack/player'
   import '@vocalstack/player/style.css'
   
   export function Videos({ codes }: { codes: string[] }) {
     return codes.map((code) => <VocalStackPlayer key={code} id={code} />)
   }
   

   Anyone with a share code can open that transcript at /v1/shares/{code}: share only what you mean to publish.

import { VocalStack } from '@vocalstack/js-sdk';

const vs = new VocalStack({ baseUrl: 'https://api.vocalstack.com', apiKey: process.env.VOCALSTACK_API_KEY });

const page = await vs.transcriptions.listPage({ q: 'interview', site: 'youtube', language: 'en', createdAfter: '2026-01-01', limit: 20 });
console.log(`${page.total} match`);

const videos = await vs.transcriptions.list({ shared: true, q: 'interview', site: 'youtube' });

const codes = videos.map((v) => v.shareCode!);
console.log(codes);

import asyncio
import os

from vocalstack import VocalStack


async def main() -> None:
    async with VocalStack("https://api.vocalstack.com", api_key=os.environ["VOCALSTACK_API_KEY"]) as vs:
        page = await vs.transcriptions.list_page(q="interview", site="youtube", language="en", created_after="2026-01-01", limit=20)
        print(f"{page.total} match")

        videos = await vs.transcriptions.list(shared=True, q="interview", site="youtube")

        codes = [v.share_code for v in videos]
        print(codes)


asyncio.run(main())

<?php
require 'vendor/autoload.php';

use VocalStack\VocalStack;

$vs = new VocalStack(apiKey: getenv('VOCALSTACK_API_KEY'), baseUrl: 'https://api.vocalstack.com');

$page = $vs->transcriptions->listPage(q: 'interview', site: 'youtube', language: 'en', createdAfter: '2026-01-01', limit: 20);
echo $page['total'], " match\n";

$videos = $vs->transcriptions->list(shared: true, q: 'interview', site: 'youtube');

$codes = array_column($videos, 'shareCode');
echo implode("\n", $codes), "\n";

#!/usr/bin/env bash
set -euo pipefail
API=https://api.vocalstack.com
AUTH="Authorization: Bearer $VOCALSTACK_API_KEY"

curl -sSfG "$API/v1/transcriptions" -H "$AUTH" \
  --data-urlencode "q=interview" -d site=youtube -d language=en -d createdAfter=2026-01-01 -d limit=20 | jq .total

curl -sSfG "$API/v1/transcriptions" -H "$AUTH" -d shared=true --data-urlencode "q=interview" -d site=youtube > shared.json

jq -r '.transcriptions[].shareCode' shared.json