> 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                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mediamelon.com/mediamelon/smartsight-apis/authentication-and-query-parameters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.