## 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..." ] } } } } } ``` ### request/poll_timeout This function is used to control how long the platform polls async provider operations before returning a continuation cursor. It allows consumers to trade lower latency for more round-trips when querying providers that use async polling (e.g., Panther, CrowdStrike, Splunk). When not specified, the platform uses its default polling budget (~275 seconds). The requested value is always capped by the context deadline — it can only shorten the polling window, never extend it. #### `request/poll_timeout()` - `seconds`: A non-negative integer representing the maximum number of seconds to spend polling. - `0` = poll-once (check status exactly once, return immediately if not done) - `> 0` = poll for up to N seconds before returning a continuation cursor - Not specified = default behavior (full context deadline) Non-polling providers safely ignore this value with no behavior change. #### Examples - `request/poll_timeout(30)` - `request/poll_timeout(0)` - `request/poll_timeout(120)` #### Meta Return This function does not produce output in the `meta` response object. Its effect is purely on execution timing. If the requested timeout exceeds the context deadline, the effective value is capped and an informational Problem message is included in the response: ```json { "messages": { "problems": [ { "message": "Poll timeout capped to context deadline", "detail": "Requested poll timeout (300s) exceeds context deadline; using 275s instead.", "status": 200, "instance": "poll-timeout-capped" } ] } } ``` ### 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, } } } } ``` ### mapping/chains This function is used to retrieve information about the mapping chains that were applied during data transformation operations. It shows which specific mappings were executed for each operation, helping with debugging, auditing, and understanding data transformation flows. For more information on the mapping IDs see the [Adaptive Mapping](/api-reference/adaptive-mapping) documentation. #### `mapping/chains(<[filters...]>)` * `[filters...]`: Optional. An array of strings representing operation IDs to include in the response. If excluded, all operation IDs with their mapping chains are returned. These filters support wildcards similar to the `api/response` function. * **Exact match:** `operation_id` - Include only the specified operation ID * **Prefix wildcard:** `*suffix` - Include operation IDs ending with the specified suffix * **Suffix wildcard:** `prefix*` - Include operation IDs starting with the specified prefix * **Contains wildcard:** `*substring*` - Include operation IDs containing the specified substring * **OR logic:** Multiple filters use OR logic - if ANY filter matches, the operation is included #### Examples * `mapping/chains()` * `mapping/chains([edr_query_alerts])` * `mapping/chains([edr_*])` * `mapping/chains([*-create, *-read])` #### Meta Return The API return will include meta data shaped similarly to the following: `mapping/chains()` ```json { "meta": { "mapping": { "chains": { "identity_query_users": [ "okta-users-transform:2", "synqly-default.ocsf:0" ] } } } } ```