/search output parameters
Use these parameters to define the output returned by /search
requests.
Format
Defines the output type for request results.
- format=$format
Identifies the output format for results, where $format is
csv
orjson
. The default value isjson
.format=csv
is valid only whenoutput=summary
.
Output type
Specifies the level of detail included with /search
responses, and determines the other options available for refining that detail.
- output=$type
Specifies the type of results to be returned. Acceptable values are
count
,details
,summary
, andzip
.- count
Returns the number of records that matched the query. Search term options may be specified after
output=count
.- details
Returns full JSON transcripts for each match. Search terms and output sorting options may be included after
output=details
.- summary
- Returns a summary of the matching search results in JSON or CSV.
summary
is the default value, and is used when no otheroutput
value is specified. After specifying theoutput=summary
option on the command line, in a JSON file, or by using it as a default value that you are not overriding, you can also specify search term, and output sorting, field, and format options.Note: When CSV reports are generated with the API, columns are always sorted alphabetically. Prior to V‑Spark version 4.3.2, columns were sorted in the order specified for thefields
parameter. - zip
Returns all files that matched your query in a zip file. The zip file that is returned includes these audio files hierarchically. After specifying the
output=zip
option on the command line or in a JSON file, you can also specify search term and output sorting options. You can also pass thezipfiles=
parameter to identify the files that you want to be included in the output zip file. This must be one or more ofjson
,mp3
, ortext
. Specifying multiple values is done as a comma-separated list.
When explicitly specified in a JSON file as part of a
/search
POST call, theoutput
value is specified as the following in your JSON file of search specifications:"output" : "value"
Fields in summary output
When specifying output=summary
in a /search
request, use the fields
parameter to define the data fields to be included with or excluded from search results.
Multiple fields may be provided in a comma-separated list. To exclude a field from search results, add a hyphen -
before the name of the field.
The following section lists all output field option parameters and describes the fields they return when specified:
- voci
Fields that are specific to audio data that has been processed by V‑Spark. This is the default behavior if no value for the
fields
option is specified.voci
fields include the following:- agent_clarity
How clear the agent channel/speech is, expressed as a value between 0 and 1, where 1 is highest.
- agent_emotion
Overall agent emotional intelligence assessment derived from both acoustic and linguistic information. Has one of the following values:
Positive
,Worsening
,Improving
, orNegative
.- agent_gender
Agent gender, either
Male
orFemale
.- agentid
Identifier for a specific agent.
- client_clarity
How clear the client channel/speech is, expressed as a value between 0 and 1, where 1 is highest.
- client_emotion
Overall agent emotional intelligence assessment derived from both acoustic and linguistic information. Has one of the following values:
Positive
,Worsening
,Improving
, orNegative
.- client_gender
Client gender, either
Male
orFemale
.- datetime
Transcript date and time. Data for the
datetime
field is stored using the organization's time zone, which may vary by organization.- diarization
Only provided in two-speaker, one-channel calls; a value between 0 and 1 identifies how completely the call was divided into individual speakers. A value of 1 is the best possible value for speaker separation. A value of 2 means the call was not diarized.
- duration
Call duration.
- es_doc_id
Unique identifier for a transcript in Elasticsearch index. Not included when
voci
is specified as return field.- filename
Name of the uploaded audio or JSON file that contains matches for the search request.
- folder
Name of the folder where the file was uploaded. Not included when
voci
is specified as return field.- last_modified
The date and time at which an update to the
last_modified
field was last triggered in the Elasticsearch record associated with a transcript. If thelast_modified
field is not present or has no date and time value, its return value isfalse
. Data for thelast_modified
field is stored in Coordinated Universal Time (UTC).The following events trigger an update to the
last_modified
field:Creating a new transcript.
Updating transcript scores by reprocessing an application.
Deleting an application or application category associated with the transcript.
Unlinking an application from the transcript's folder, if that application has previously been used to score the transcript.
Updating transcript metadata using the API.
- overall_emotion
Overall emotional intelligence assessment for an audio file, derived from both acoustic and linguistic information. Has one of the following values:
Positive
,Worsening
,Improving
, orNegative
.- overtalk
Percentage of call when the agent talks over or interrupts the client. Equal to the number of turns where the agent initiated overtalk divided by the total number of agent turns.
- preview
An excerpt of the transcribed call in which matched terms are highlighted.
- requestid
Unique identifier for a transcription request. This value is assigned when an audio file is submitted for transcription.
- score
Calculation of how well a transcript matches the terms specified in your search. This is represented as a value between 0 and 1, and can depend on the type of query that you submitted. For example, date range queries always provide a score value of 1 for any transcription that occurred in the specified date range.
- silence
Percentage of call duration that is silence. Equal to all non-speech time, this value is calculated as call duration minus the sum of the duration of each word. If music and noise are not decoded to word-events, they are counted as silence.
- tags
Tags added to files in the GUI. Not included when
voci
is specified as return field.- tid
Unique identifier for a transcript.
- url
URL to visit the file details in the GUI. Not included when
voci
is specified as return field.
- $custom_metadata
Custom metadata fields, specified by name, configured for the folder that processed the audio.
- all
Combination of all
voci
and $custom_metadata fields.- apps
Scores for all applications. Requests may specify either
apps
orapp. $appname
, not both.- app.$appname
Scores for a specific application. Requests may specify either
apps
orapp. $appname
, not both.- app.$appname.$top_category
Scores for a specific category in an application. Note that the category's full name includes its parents' names, including any parent categories. For example,
app.$appname .$top_category.$lower_category
refers to an application category called $lower_category, which is a child of $top_category and $appname.
Sort
The V‑Spark /search
API provides multiple parameters that enable you to specify the way in which search results should be sorted. You can specify these parameters when using any /search
API output
type with the exception of the count
output type.
Possible sorting output options are the following:
- offset=$number
Specifies the number of the first search result that should be returned. The
offset
is used in conjunction with thesize
option to enable you to page through search results when their number exceeds thesize
value. For example, if a search matches 500 results and you are using asize
value of 100, you would specify&offset=100
to return results 101-200, and&offset=200
to return results 201-300, and so on. The defaultoffset
value is0
.- size=$number
Specifies the number of matching results that will be returned at one time. The default
size
value is100
. The maximum value forsize
is 1000.- sort=$field
Specifies how matching search results should be ordered when returned. Regardless of the specified $field,
score
is always used as a secondary sort option. The defaultsort
value isdatetime
.$field accepts these values as sort options:
agent_clarity
agent_emotion
agent_gender
client_clarity
client_emotion
client_gender
datetime
diarization
duration
filename
last_modified
overall_emotion
overtalk
score
silence
- sortdir=$direction
Direction in which to sort output entries. $direction should be either
asc
for ascending order, ordesc
for descending order, based on data type. The default value isdesc
.