> For the complete documentation index, see [llms.txt](https://docs.mediamelon.com/mediamelon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediamelon.com/mediamelon/smartsight-apis/authentication-and-query-parameters.md).

# Authentication and query parameters

Authenticate every request with your API key.

```http
X-API-Key: <your-api-key>
```

Contact MediaMelon support or your account team to obtain your API key.

### Example API request

This example uses the metric query endpoint with shared query parameters:

* `period=start=1775749920,end=1775836379`
* `metrics=latency,viewercount`
* `aggby=timestamp`
* `granularity=hour`
* `orderby=timestamp`
* `order=asc`

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/metricquery/199493832?period=start=1775749920,end=1775836379&metrics=latency,viewercount&aggby=timestamp&granularity=hour&orderby=timestamp&order=asc' \
  --header 'X-API-Key: <your-api-key>'
```

### Getting started

1. Get your customer ID from your SmartSight profile.
2. Obtain your API key.
3. Choose an endpoint.
4. Build a query with `period` and `metrics`.
5. Send the request with the `X-API-Key` header.

### Common query parameters

<table><thead><tr><th width="162.0859375">Parameter</th><th width="116.8203125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>period</code></td><td>Yes</td><td><code>start=&#x3C;epoch_seconds>,end=&#x3C;epoch_seconds></code></td></tr><tr><td><code>metrics</code></td><td>Yes</td><td>Comma-separated metric field names</td></tr><tr><td><code>aggby</code></td><td>No</td><td>Breakdown by a combination of dimension or <code>timestamp</code> for time-series</td></tr><tr><td><code>filter</code></td><td>No</td><td>Dimension filters, such as <code>[country=US|Canada][platform=Android]</code></td></tr><tr><td><code>qoefilter</code></td><td>No</td><td>Metric-level conditions to filter, such as <code>latency>3 AND bufferingratio>5</code></td></tr><tr><td><code>orderby</code></td><td>No</td><td>Sort by metric or dimension name</td></tr><tr><td><code>order</code></td><td>No</td><td>Sorting order - <code>asc</code> or <code>desc</code></td></tr><tr><td><code>limit</code></td><td>No</td><td>Number of records to include in the response, aka Page size. Default is <code>1000</code></td></tr><tr><td><code>offset</code></td><td>No</td><td>Record offset to include from in the response. Default is <code>0</code></td></tr></tbody></table>

{% hint style="info" %}
Use `aggby=timestamp` with `granularity` for time-series queries. Use `aggby=<dimension>` for breakdown tables.
{% endhint %}

### Response structure

{% code lineNumbers="true" %}

```json
{
  "totalcount": 25,
  "pagecount": 4,
  "totalrecords": 100,
  "response": [
    {
      "country": "US",
      "latency": 1.82,
      "concurviewavg": 412
    },
    {
      "country": "GB",
      "latency": 2.14,
      "concurviewavg": 187
    }
  ]
}
```

{% endcode %}

| Field          | Description                                  |
| -------------- | -------------------------------------------- |
| `totalcount`   | Number of records in the current response    |
| `pagecount`    | Total number of pages in the full result set |
| `totalrecords` | Total matching records across all pages      |
| `response`     | Array of result objects                      |