## Overview

For endpoints that support them, meta functions allow decorating responses from the Synqly API with additional meta information. Meta functions are organized into groups, representing a specific type of metadata.

## Calling Meta Functions

When making a request without a body (typically an HTTP `GET` request), add any number of `meta=` query parameters, each containing a single meta function.


```
GET
https://api.synqly.com/v1/siem/event?meta=stats/count([raw_data.time])&meta=api/response(primary)
```

For requests that do take a JSON body, include the meta functions in a root-level `meta` key as an array of function calls.


```
POST
https://api.synqly.com/v1/example
{
    "meta": [ "api/response(all)" ]
}
```

### SDKs

Each SDK will have a means of taking meta functions for calls to endpoints that support it.

*Note: To avoid type issues make sure your SDK version is `0.2.55` or later.*

For the [Go SDK](https://github.com/Synqly/go-sdk) the example `GET` call above could be made like this:


```go
queryResponse, err := apiClient.Siem.QueryEvents(ctx, &engine.QuerySiemEventsRequest{
    Meta: []*string{engine.String("stats/count([raw_data.time])"), engine.String("api/response(primary)")},
})
```

Using our [Python SDK](https://github.com/Synqly/python-sdk), that same call looks like this:


```python
query_response = api_client.siem.query_events(
    meta=[
        "stats/count([raw_data.time])",
        "api/response(primary)",
    ],
)
```

Review the documentation for each specific SDK to best determine how the call arguments provided for that language.

## Responses

When a Synqly endpoint supports meta functions, the returned data will include a top level "meta" item. This will then provide results organized first by group, then by function.

`https://api.synqly.com/v1/siem/event?meta=stats/count()&meta=api/response(primary)`


```json
{
    "response": {},
    "cursor": "...",
    "meta": {
        "api": {
            "response": {
                "primary": {
                    "url": "https://example.com/api/getThing",
                    "response": "...raw response string..."
                }
            }
        },
        "stats": {
            "count": {
                "*": 308
            }
        }
    }
}
```

## Available Functions

Look at individual endpoints to determine support for a specific meta function.

### api/response

This function is used to include the raw response from API calls made from Synqly to the provider API.

#### `api/response(responses, <[filters...]>`

* `responses`: An enum, it must be 'primary', 'list', or 'all'.
  * **primary:** Include the raw response for the 'primary' call in the meta response. This is generally the final call that populates the data in the Synqly response.
  * **list:** Include all raw responses for made to the backing provider API, organized by URL, filtered by any `filters...`.
  * **all:** Include both the singled out 'primary' response as well as the list of all responses, filtered by `filters...`.
* `[filters...]`: Optional. An array of strings. This represents an allow list of URLs to include the the responses list. These filters can contain leading or trailing `*` s to indicate wildcards.


#### Examples

* `api/response(primary)`
* `api/response(list)`
* `api/response(list,[http://example.com/api/call, http://sub.example.com/api/call?filter=example&limit=5] api/response(all)`
* `api/response(all, [http://example.com*, */api/call, *filter=example*]`


#### Meta Return

The API return will include meta data shaped similarly to the following:

`api/response(all)`


```json
{
    "meta": {
        "api": {
            "response": {
                "primary": {
                    "url": "https://example.com/api/v1/getThing",
                    "response": "...raw response string..."
                },
                "list": {
                    "https://example.com/api/v1/getThing": [
                        "...raw response string..."
                    ],
                    "https://example.com/api/v1/polledSupportingCall": [
                        "...first call raw response string...",
                        "...second call raw response string...",
                        "...third call raw response string..."
                    ]
                }
            }
        }
    }
}
```

### stats/count

This function is used to calculate count statistics on a returned set of data. Without argument it returns the total count of items available. With arguments, it breaks up the count into facet by any passed `facets` fields.

#### `stats/count(<[facets...]>`

* `[facets]`: Optional. If excluded, the total count is returned. If included, each provided value will further break up the data, returning an individual count for each bucket.


*Note: For many providers, running a statistics query is performed as an alternative to a data query. As a result, running a stats query may populate the response meta, but result in an empty data set.*

#### Examples

* `stats/count()`
* `stats/count([time])`
* `stats/count([raw_data.message, raw_data.activity_id])`


#### Meta Return

The API return will include meta data shaped similarly to the following:

`stats/count()`


```json
{
    "meta": {
        "stats": {
            "count": {
                "*": 345
            }
        }
    }
}
```

`stats/count([raw_data.message, raw_data.activity_id])`


```json
{
    "meta": {
        "stats": {
            "count": {
                "message:example1,activity_id:1": 21,
                "message:example2,activity_id:1": 55,
                "message:example1,activity_id:2": 146,
                "message:example2,activity_id:2": 123,
            }
        }
    }
}
```