> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/api-docs-voice/standard-package/voice-sampling-api.md).

# Voice Sampling API

\[ Base URL: `api.ggwp.com`]

`POST` /voice/v1/sample

## **Description**

The Voice Sampling endpoint receives a User ID and Session ID and returns a boolean to decide if the user's audio in that session should be sent for processing. This endpoint is only applicable for clients that want to process a portion of total audio volume for cost predictability.

As an illustrative example, a client may want to process 100,000 monthly audio hours out of their expected 200,000 total. There are simple means to do this sampling, such as randomly excluding 50% of audio clips from being sent or stop sending after hitting the 100,000 limit, but they do not take advantage of context like the user's past behavior or whether someone has muted them in the session.

The Voice Sampling endpoint allows GGWP to manage a smart customizable sampling approach using available context to maximize your monthly hours while exposing the logic through a simple API. Clients may call this endpoint once for each user at the beginning of a new session, and use the output boolean to decide if the user's audio should be sent. On the backend, GGWP uses each user's reputation score and any received contextual data (such as mutes or friend graphs) to moderate the most pertinent conversations.

<figure><img src="/files/bq2LmWf1NZ4I0T5hcjPc" alt=""><figcaption><p>Voice Sampling Illustration</p></figcaption></figure>

***Note**: sampling always reduces moderation effectiveness as there is no lightweight method to cleanly separate safe audio from incident audio. However if you must sample, usually as a cost control, then using this endpoint will help maximize your monthly hours as easily as possible.*

## **Parameters**

The following parameters are required in the POST request:

* **data:** a dictionary containing the following fields:
  * **user\_id:** the user that is being considered for sampling.
    * Example: `player10`
  * **session\_id:** the session (e.g. conversation) in which the user is being considered for sampling. For match-based games, this will be the match ID.
    * Example: `match_unranked_20230620_12345`
* **headers**
  * **x-api-key:** the GGWP API key corresponding to your organization and dashboard.

## **Example Call**

**Bash**

```bash
curl --location --request POST 'https://api.ggwp.com/voice/v1/sample' \
--header 'x-api-key: GGWP_API_KEY' \
--data-raw '{
  "session_id": "match_unranked_20230620_12345",
  "user_id": "player10"
}'
```

**Python**

```python
import requests

# Prepare the headers and data body
headers = {
    "x-api-key": "GGWP_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "user_id": "player10",
    "session_id": "match_unranked_20230620_12345"
}

# Send the POST request with headers
response = requests.post(
    'https://api.ggwp.com/voice/v1/sample',
    headers=headers,
    json=data
)

# Examine the response
print(response.json())
```

## **Output**

* 200 response - successful operation

  ```bash
  {
      "user_id": "player10",
      "session_id": "match_unranked_20230620_12345",
      "sample": true
  }
  ```
* 400
  * Invalid input parameters
* 403
  * Invalid or missing API key
* 500
  * Server-side error response