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.
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.