V-Spark Online Help

Search Term Options

The types of searches that you can perform using the V‑Spark/search API demonstrate its power and flexibility. Search parameters and potential values are the following:

agent_clarity=N-M

Search for audio records with agent voice clarity percentage within the range of N to M, which are floating point values. Agent voice clarity measures how clear the agent sounds in the recorded audio. Agents with a clarity of "1" would be the clearest. Low clarity is the result of poor signal, background noise, accent, or poor enunciation.

agent_emotion=EMOTION

Search for audio records where the emotional score of the agent's portion of the audio is EMOTION. Possible values for EMOTION are improving, negative, positive, and worsening. Only one agent_emotion value can be used within a single search. For example:

agent_emotion=negative
agent_gender=GENDER

Search for audio records where the gender of the agent has been identified as GENDER. Possible values for GENDER are female and male. Only one agent_gender value can be used within a single search. For example:

agent_gender=female
app.name=APPNAME and app.CATEGORY=SCORE

Search for transcripts that have received the specified SCORE level from the V‑Sparkapplication named APPNAME in the specified top-level category, or optional lower-level category of that category. Specify lower-level categories using a full dot-separated path through the category tree. For example: app.TOP_CATEGORY.LOWER_CATEGORY.LOWER_CATEGORY Score level may be one of the following values:

  • All - Score greater than 0

  • High - Score greater than 0.66

  • Medium - Score greater than 0.33

  • Low - Score between 0 and 0.33

  • None - Score of 0

client_clarity=N-M

Search for audio records with client voice clarity percentage within the range of N to M, which are floating point values. Client voice clarity measures how clear the client sounds in the recorded audio. Clients with a clarity of "1" would be the clearest. Low clarity is the result of poor signal, background noise, accent, or poor enunciation.

client_emotion=EMOTION

Search for audio records where the emotional score of the client's portion of the audio is EMOTION. Possible values for EMOTION are improving, negative, positive, and worsening. Only one client_emotion value can be used within a single search. For example:

client_emotion=improving
client_gender=GENDER

Search for audio records where the gender of the client has been identified as GENDER. Possible values for GENDER are female and male. Only one client_gender value can be used within a single search. For example:

client_gender=male
daterange=START-END

Search for audio records with a datetime value in the range of START to END. Data for the datetime field is stored using the organization's time zone, which may vary by organization.

Values for START and END are optional. The range specified by START and END may be expressed using any combination of years, months, days, hours, minutes, and seconds, expressed as YYYYMMDD[HHmmss]. Date ranges are always assumed to be positive (where START is less than END) and expressed in the organization's time zone.

Note

No verification is done to ensure that daterange values are correct; invalid date ranges will simply return no values. If START is not specified, a default value of 01 January, 1900 is used. If END is not specified, the current date is used.

diarization=SCORE

Search for audio records with a diarization score of at least SCORE. which is a floating point value between 0 and 1. When mono (single-channel) audio has multiple speakers, diarization can separate the speakers for analysis. The diarization score identifies how completely the call was divided into individual speakers. A score of 2 means the call was not diarized. Diarization technology is not perfect, and to find calls where diarization is done well, set SCORE closer to one than to zero. The tradeoff is that fewer calls will be retrieved.

duration=N-M

Search for audio records with durations in the range of N to M, where N and M are the minimum and maximum durations, respectively, of the audio records to be returned. Note the following:

  • The durations N and M can be expressed in the colon-delimited format hh:mm:ss.

  • Only the seconds (ss) value is required; hours (hh) and minutes (mm) are optional.

  • The colon delimiter is required only when specifying hours or minutes.

  • There is no limit to the numeric values of hours, minutes, or seconds.

  • Only the first value, N, is required, along with the hyphen. Omitting M will search for all audio records with duration greater than the minimum value N.

For example, to search for audio records with duration 30 minutes to 60 minutes, use any of the following:

duration=30:00-1:00:00 
duration=30:00-60:00 
duration=1800-3600

Similarly, any of the following expressions would return audio records at least 10 minutes long:

duration=10:00-
duration=8:120-
duration=6000-
lastmodifiedrange=START-END

Search for audio records with a last_modified value in the range of START to END. Data for the last_modified field is stored using Coordinated Universal Time (UTC).

Values for START and END are optional. The range specified by START and END may be expressed using any combination of years, months, days, hours, minutes, and seconds, expressed as YYYYMMDD[HHmmss]. Date ranges for lastmodifiedrange are always assumed to be positive (where START is less than END) and expressed in Coordinated Universal Time (UTC).

Note

Records without a date and time value for the last_modified field will not be included in results.

overall_emotion=EMOTION

Search for audio records where the overall emotional score of the audio is EMOTION. Possible values for EMOTION are improving, negative, positive, and worsening. Only one overall_emotion value can be used within a single search. For example:

overall_emotion=positive
overall_gender=GENDER

Search for audio records where the overall gender of the speakers has been identified as GENDER. Possible values for GENDER are female and male. Only one overall_gender value can be used within a single search. For example:

overall_gender=male
overtalk=N-M

Search for audio records with overtalk percentages within the range of N to M, which are floating point values. Overtalk occurs when speakers talk over one another. A recording's ovetalk percentage is the count of Agent-initiated overtalk turns as a percentage of the total number of Agent speaking turns. In other words, out of all of the Agent’s turns, it measures how many turns interrupted a Client’s turn. An overtalk value of "1" indicates the most overtalk.

silence=N-M

Search for audio records with silence percentages within the range of N to M, which are floating point values. Silence is equal to all non-speech time, as a percentage of the total audio duration. If music and noise are not decoded to word-events, they are counted as silence. Calls with a silence value of "1" contain the most silence.

terms.FIELD=VALUE

Fields that can identified for searching are the following:

  • agent

  • agentid

  • client

  • file

  • requestid

  • speakers

  • tag

  • tid

  • CLIENT-DATA - search any of the custom metadata fields that have been entered within the folder with which your audio files are associated

Include multiple terms in the value by using a comma-separated list.

terms.op=OPERATOR

Combine multiple search terms (and therefore, their associated fields) by using a logical and or or operator, where and is the default operator. For example:

terms.tid=1,2&terms.op=or