Format

Defines the output type for request results.

format=$format

Identifies the output format for results, where $format is csv or json. The default value is json. format=csv is valid only when output=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, and zip.

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 other output value is specified. After specifying the output=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 the fields 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 the zipfiles= parameter to identify the files that you want to be included in the output zip file. This must be one or more of json, mp3, or text. Specifying multiple values is done as a comma-separated list.

When explicitly specified in a JSON file as part of a /search POST call, the output 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, or Negative.

agent_gender

Agent gender, either Male or Female.

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, or Negative.

client_gender

Client gender, either Male or Female.

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 the last_modified field is not present or has no date and time value, its return value is false. Data for the last_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, or Negative.

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 or app. $appname , not both.

app.$appname

Scores for a specific application. Requests may specify either apps or app. $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 the size option to enable you to page through search results when their number exceeds the size value. For example, if a search matches 500 results and you are using a size 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 default offset value is 0.

size=$number

Specifies the number of matching results that will be returned at one time. The default size value is 100. The maximum value for size 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 default sort value is datetime.

$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, or desc for descending order, based on data type. The default value is desc.