List Objects#

You can retrieve a list of stored objects using the ListObjects API call. This returns only basic information about stored objects, not the content.

Example#

This example demonstrates how to retrieve a list of the first 10 objects stored in January 2023.

list_objects.py

from datetime import datetime

from soniox.speech_service import SpeechClient
from soniox.storage import list_objects


# Do not forget to set your API key in the SONIOX_API_KEY environment variable.
def main():
    with SpeechClient() as client:
        # List objects.
        list_response = list_objects(
            client,
            stored_datetime_from=datetime.fromisoformat("2023-01-01T00:00+00:00"),
            stored_datetime_to=datetime.fromisoformat("2023-02-01T00:00+00:00"),
            start=0,
            num=10,
        )

        # Print objects.
        for obj in list_response.objects:
            print(f"Object ID: {obj.object_id}")


if __name__ == "__main__":
    main()

Parameters#

Stored Datetime#

stored_datetime_from and stored_datetime_to are optional parameters that limit results based on the time when the object was stored (stored_datetime field in the StoredObject structure). stored_datetime_from is inclusive while stored_datetime_to is non-inclusive.

If you want to list objects based on date rather than datetime:

  • To list from some date, set stored_datetime_from to that date and time 00:00.
  • To list up to some date, set stored_datetime_to to that date plus one day and time 00:00.
  • To list for a specific date, do both of the above.

Result Range#

You can obtain only a specific range of object results using the start and num parameters.

  • start defines the index of the first returned result. If it is 0 (the default), results are returned from the start.
  • num defines the desired number of results to return. If it is 0 (the default), a specific default number (currently 500) will be used. Otherwise, the number will still be limited to a specific maximum number (currently 5000).

In order to enumerate all stored objects in a given time range (if any), first call with ListObject with start=0, and then repeat the call with start equal to response.start + len(response.objects) until len(response.objects) == 0.

Response#

The ListObjectsResponse structure contains all information returned by ListObject.

message ListObjectsResponse {
    int64 start = 1;
    repeated ListObjectsResponseObject objects = 2;
}
  • start is the index of the first returned result, as in the request.
  • objects are the returned objects.
message ListObjectsResponseObject {
    string object_id = 1;
    google.protobuf.Timestamp stored_datetime = 2;
    bool audio_stored = 3;
    bool transcript_stored = 4;
    int32 audio_duration_ms = 5;
    int32 stored_audio_ms = 6;
}
  • object_id is the object ID.
  • stored_datetime is the datetime when the object was stored.
  • audio_stored indicates if audio is stored.
  • transcript_stored indicates if the transcript is stored.
  • audio_duration_ms is the audio duration in milliseconds.
  • stored_audio_ms is the duration of stored audio counting each audio channel individually. This duration is used for billing of audio storage.