# Supermetrics

> Query marketing data and discover Supermetrics data sources, fields, accounts and saved queries.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/supermetrics

## Actions

### Create a new account tag

Create an account tag.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Display name (`display_name`, text, required): Display name for the new account tag
- Color (`color`, text, required): Color for the new account tag
- Data sources (`data_sources`, list, required): Array of data sources and connections

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": {
      "color": "example",
      "data_sources": [],
      "display_name": "example",
      "name": "example"
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Delete an account tag

Delete an account tag.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Name (`name`, text, required): The unique name of the account tag

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": {
      "result": false
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get accounts

List the data source logins available to you and the accounts each one can reach.

**Inputs**

- Ds id (`ds_id`, text, required): Data source ID
- Ds users (`ds_users`, text): Comma-separated list of usernames. Defaults to all available.
- Cache minutes (`cache_minutes`, number): Maximum allowed age of the cached accounts in minutes. Defaults to none for last fetched data. From 60 to 1440.

**Outputs**

- `data` (object): Output object containing fetched account data and metadata.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "query": {
        "cache_minutes": 1
      },
      "request_id": "example"
    }
  }
}
```

### Get available sources

List the data sources and destinations available for a Hub transfer. You need permission to view transfers. Your team can call it at most once every 200 milliseconds.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.

**Outputs**

- `data` (object): Available data sources and destinations for Hub transfers

**Example output**

```json
{
  "data": {
    "data_sources": [],
    "destination_types": [],
    "destinations": []
  }
}
```

### Get fields

List the standard and custom fields available for a data source.

**Inputs**

- Ds id (`ds_id`, text, required): Data source ID
- Ds accounts (`ds_accounts`, text): Comma-separated list of account IDs to target. Required to return custom fields.
- Ds users (`ds_users`, text): Comma-separated list of usernames. Required when ds_accounts is provided to return custom fields.

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get login

Get the details of one data source login.

**Inputs**

- Login (`login_id`, text, required): Entity login ID

**Outputs**

- `data` (object): Response envelope containing a single data source login

**Example output**

```json
{
  "data": {
    "data": {
      "@type": "ds_login",
      "additional_scopes": [],
      "auth_time": "example",
      "auth_user_info": {
        "@type": "user",
        "email": "example",
        "user_id": "example"
      },
      "default_scopes": [],
      "display_name": "example",
      "ds_info": {
        "@type": "ds",
        "ds_id": "example",
        "name": "example"
      },
      "expiry_time": "example",
      "is_refreshable": false,
      "is_shared": false,
      "login_id": "example",
      "login_type": "example",
      "revoked_time": "example",
      "username": "example"
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get query

Get one saved query.

**Inputs**

- Query (`query_id`, text, required): Entity query ID

**Outputs**

- `data` (object): Response envelope containing a single saved query

**Example output**

```json
{
  "data": {
    "data": {
      "@type": "query",
      "ds_info": {
        "@type": "ds",
        "ds_id": "example",
        "name": "example"
      },
      "group_info": {
        "@type": "query_group",
        "group_id": "example",
        "name": "example"
      },
      "modified_time": "example",
      "name": "example",
      "query_id": "example",
      "query_params": {},
      "slug": "example"
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get query results

Get the results of a recently run query, in the format it was requested in.

**Inputs**

- Schedule id (`schedule_id`, text, required): Query schedule ID
- Offset (`offset`, number): Pagination offset for the number of result rows to return. Defaults to 0. From 0 to 1000000. Default: `0`.
- Limit (`limit`, number): Maximum number of result rows to return. From 1 to 100000. Default: `100`.

**Outputs**

- `data` (object): The query results in the requested output format.

**Example output**

```json
{
  "data": {}
}
```

### Get query status

Get the status and results of a query running in the background.

**Inputs**

- Schedule id (`schedule_id`, text, required): Query schedule ID
- Offset start (`offset_start`, number): Starting row index for a paginated response. Defaults to 0. From 0 to 1000000. Default: `0`.
- Offset end (`offset_end`, number): Ending row index for a paginated response. Defaults to none for all the data. From 0 to 1000000.

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "progress": {
        "queries_ready": 1,
        "queries_total": 1
      },
      "request_id": "example",
      "schedule_id": "example",
      "status_code": "SCHEDULED",
      "workflow": {
        "tasks_running": 1,
        "tasks_scheduled": 1
      }
    }
  }
}
```

### Get release statuses

List the release statuses you can filter a data source search by.

**Inputs**: None.

**Outputs**

- `data` (object): Response envelope listing data source release statuses for search filtering.

**Example output**

```json
{
  "data": {
    "data": {
      "list": {}
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get search categories

List the categories you can filter a data source search by.

**Inputs**: None.

**Outputs**

- `data` (object): Response envelope listing data source categories for search filtering.

**Example output**

```json
{
  "data": {
    "data": {
      "list": {}
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get search tags

List the tags you can filter a data source search by.

**Inputs**: None.

**Outputs**

- `data` (object): Response envelope listing data source tags for search filtering.

**Example output**

```json
{
  "data": {
    "data": {
      "list": {}
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Get segments

List your team's data source logins and the segments available for each.

**Inputs**

- Ds id (`ds_id`, text, required): Data source ID
- Ds users (`ds_users`, text): Comma-separated list of usernames. Defaults to all available.
- Cache minutes (`cache_minutes`, number): Maximum allowed age of the cached segments in minutes. Defaults to none for last fetched data. From 60 to 1440.

**Outputs**

- `data` (object): List of data source segments and metadata.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "query": {
        "cache_minutes": 1
      },
      "request_id": "example"
    }
  }
}
```

### Get transfer configuration

Get the full configuration of an existing Hub transfer. You need permission to view transfers. Your team can call it at most once every 200 milliseconds.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Transfer id (`transfer_id`, number, required): Unique identifier for the transfer. At least 1.

**Outputs**

- `data` (object): Full transfer configuration

**Example output**

```json
{
  "data": {
    "accounts": [],
    "data_source": {
      "data_source_id": "example",
      "service_name": "example",
      "service_provider": "example",
      "settings": []
    },
    "destination_id": 1,
    "display_name": "example",
    "external_url": "example",
    "license": {
      "end_date": "example",
      "features": {},
      "id": 1,
      "is_expired": false,
      "is_trial": false,
      "license_title": "example",
      "product_title": "example"
    },
    "notification_recipients": [],
    "schedule": [],
    "schema_id": 1,
    "segments": [],
    "transfer_id": 1
  }
}
```

### Get transfer options

Get the settings available for a Hub transfer from a given data source to a given destination. You need permission to view transfers. Your team can call it at most once every 200 milliseconds.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Source id (`source_id`, text, required): Data source identifier
- Destination id (`destination_id`, number, required): Destination identifier

**Outputs**

- `data` (object): Transfer configuration options for a given source/destination combination

**Example output**

```json
{
  "data": {
    "accounts": [],
    "data_source": {
      "data_source_id": "example",
      "service_name": "example",
      "settings": []
    },
    "license": {},
    "logins": [],
    "schedule_options": [],
    "schemas": [],
    "segments": []
  }
}
```

### Get transfer run details

Get one run of a transfer that belongs to your team, with its status, timing, row counts and the details of each query it ran. You need permission to view transfers. Your team can call it at most once every 200 milliseconds.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Transfer run id (`transfer_run_id`, number, required): Unique identifier of the transfer run. At least 1.

**Outputs**

- `data` (object): Response envelope containing a single transfer run detail.

**Example output**

```json
{
  "data": {
    "data": {
      "created_time": "example",
      "data_date": "example",
      "ended_time": "example",
      "external_id": "example",
      "failed_query_amount": 1,
      "id": 1,
      "message": "example",
      "query_amount": 1,
      "query_details": [],
      "queued_time": "example",
      "started_time": "example",
      "status": "example",
      "total_duration": 1.0,
      "total_rows": 1
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### List all account tags in a team

List all of your team's account tags.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": {
      "items": []
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### List login accounts

List the stored accounts for a data source login.

**Inputs**

- Login (`login_id`, text, required): Entity login ID
- Offset (`offset`, number): Pagination offset for the number of items to return. Defaults to 0. From 0 to 1000000. Default: `0`.
- Limit (`limit`, number): Maximum number of items to return. Defaults to 100, maximum of 1000 is enforced. From 1 to 1000. Default: `100`.

**Outputs**

- `data` (object): Paginated response envelope containing a list of stored data source accounts for a login

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "paginate": {
        "limit": 1,
        "offset": 1,
        "total": 1
      },
      "request_id": "example"
    }
  }
}
```

### List logins

List all of your team's data source logins.

**Inputs**: None.

**Outputs**

- `data` (object): Response envelope containing a list of data source logins

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "request_id": "example"
    }
  }
}
```

### List queries

List your saved queries.

**Inputs**: None.

**Outputs**

- `data` (object): Response envelope containing a list of saved queries

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "request_id": "example"
    }
  }
}
```

### List transfer runs

List the runs of one of your team's transfers between a start and end date, 100 a page by default and up to 10,000. You can filter by issues and sort the results. Your team can call it at most once every 200 milliseconds.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Transfer id (`transfer_id`, number, required): Unique identifier of the transfer. At least 1.
- Start date (`start_date`, date and time, required): Start date for filtering runs (inclusive)
- End date (`end_date`, date and time, required): End date for filtering runs (inclusive)
- Filter issues only (`filter_issues_only`, true/false): Filter to show only runs with issues
- Sort field (`sort_field`, text): Field to sort by. One of: `created_time` (Created time), `ended_time` (Ended time), `data_date` (Data date).
- Sort direction (`sort_direction`, text): Sort direction. One of: `ASC`, `DESC`.
- Limit (`limit`, number): Maximum number of results to return (default 100, max 10000). At least 1. Default: `100`.
- Offset (`offset`, number): Number of results to skip for pagination. At least 0. Default: `0`.

**Outputs**

- `data` (object): Response envelope containing a list of transfer runs.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "request_id": "example"
    }
  }
}
```

### List transfers

List your team's transfers that haven't been deleted, with basic details for each. You need permission to view transfers. Your team can call it at most once every 200 milliseconds.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Limit (`limit`, number): Maximum number of transfers to return. When omitted, all transfers are returned (backward compatible). Capped at 5000. From 1 to 5000.
- Offset (`offset`, number): Number of transfers to skip before returning results. Only applies when limit is also provided. When omitted, defaults to 0. At least 0.
- Include total count (`include_total_count`, true/false): When true, include total count in the pagination object. Requires an additional COUNT query. Omit for better performance when total is not needed ; use `has_more` and `next_offset` for efficient pagination.

**Outputs**

- `data` (object): Response envelope containing a list of transfers.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "request_id": "example"
    },
    "pagination": {
      "has_more": false,
      "limit": 1,
      "next_offset": 1,
      "total": 1
    }
  }
}
```

### Query data

Run a query against a data source and return the data.

**Inputs**

- Schedule id (`schedule_id`, text): Custom query schedule ID
- Sync timeout (`sync_timeout`, number): Wait up to 20 seconds for results. Check the returned schedule ID with Get query status and Get query results if it is still running. From 0 to 20. Default: `20`.
- Api links (`api_links`, list): Types of resource links to return. Not in use.
- Ds id (`ds_id`, text, required): Data source ID
- Ds accounts (`ds_accounts`, text): List of data source account IDs to query
- Ds segments (`ds_segments`, text): List of data source segment IDs to query
- Ds user (`ds_user`, text): Shorthand parameter to provide one value for ds_users
- Ds users (`ds_users`, text): List of data source usernames we should target
- Date range type (`date_range_type`, text): Type of date range the query should use
- Start date (`start_date`, date): Fixed or relative query start date
- End date (`end_date`, date): Fixed or relative query end date
- Compare type (`compare_type`, text): Date range comparison type
- Compare show (`compare_show`, text): Display type for comparison values
- Compare start date (`compare_start_date`, text): Fixed or relative start date for comparison date range
- Compare end date (`compare_end_date`, text): Fixed or relative end date for comparison date range
- Fields (`fields`, text): List of metric and dimension field IDs or field objects for the query
- Filter (`filter`, text): Query filter string
- Settings (`settings`, list): Additional settings for query in key-value pairs
- Order rows (`order_rows`, text): List of fields and their sorting directions for the results
- Order columns (`order_columns`, text): Order policy for fields that are split by column
- Offset start (`offset_start`, number): Starting row index for a paginated response. Defaults to 0. From 0 to 1000000. Default: `0`.
- Offset end (`offset_end`, number): Ending row index for a paginated response. Defaults to none for all the data. From 0 to 1000000.
- Max columns (`max_columns`, number): Maximum number of columns the query should return when fields are split by column. From 0 to 2147483647. Default: `20`.
- Max rows (`max_rows`, number): Maximum number of rows the query should return. Defaults to 1000. From 0 to 2147483647. Default: `1000`.
- Cache minutes (`cache_minutes`, number): Maximum allowed age of query results cache in minutes. Defaults to none for no explicit policy. From 0 to 2147483647.

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": [],
    "meta": {
      "paginate": {
        "next": "example",
        "prev": "example"
      },
      "query": {
        "cache_minutes": 1,
        "compare_end_date": "example",
        "compare_show": "example",
        "compare_start_date": "example",
        "compare_type": "example",
        "ds_accounts": [],
        "ds_segments": [],
        "end_date": "example",
        "fields": [],
        "settings": {},
        "start_date": "example"
      },
      "request_id": "example",
      "result": {
        "cache_time": "example",
        "cache_used": false,
        "data_sampled": false,
        "run_seconds": 1.0,
        "total_columns": 1,
        "total_rows": 1
      },
      "schedule_id": "example",
      "status_code": "example"
    }
  }
}
```

### Search data sources

Search the publicly available Supermetrics data sources.

**Inputs**

- Filter keyword (`filter_keyword`, text): Fuzzy search by keyword in connector ID, name, marketing name, description, categories, aliases, and tags.
- Filter category (`filter_category`, text): Filter by category. One of: `AD_VERIFICATION` (Ad verification), `AFFILIATE`, `ANALYTICS`, `BRAND_REPUTATION` (Brand reputation), `CRM_SALES` (Crm sales), `DATA_WAREHOUSES` (Data warehouses), `DSP`, `ECOMMERCE`, `FILES`, `MARKETING_ATTRIBUTION` (Marketing attribution), and 9 more.
- Filter status (`filter_status`, text): Filter by release status. One of: `DEVELOPMENT`, `INVITE_ONLY` (Invite only), `EARLY_ACCESS` (Early access), `RELEASED`, `SUNSETTED`.
- Filter product (`filter_product`, text): Filter by product. One of: `EXCEL`, `SHEETS`, `DS`, `API`, `HUB`.
- Filter tag (`filter_tag`, text): Filter by tag.
- Filter is new (`filter_is_new`, text): Filter only new connectors (release date within the last 90 days). One of: `true`, `false`.
- Filter is shown website (`filter_is_shown_website`, text): Filter only connectors shown on the website. One of: `true`, `false`.

**Outputs**

- `data` (object): Response envelope containing data source search results.

**Example output**

```json
{
  "data": {
    "data": {
      "list": []
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```

### Update an account tag

Update an account tag.

**Inputs**

- Team id (`supermetrics_team_id`, number): Leave empty to use the Team ID saved with your connection. From 1 to 9.223372036854776e+18.
- Name (`name`, text, required): The unique name of the account tag
- Display name (`display_name`, text, required): Display name for the account tag
- Color (`color`, text, required): Color for the account tag

**Outputs**

- `data` (object): Response.

**Example output**

```json
{
  "data": {
    "data": {
      "color": "example",
      "data_sources": [],
      "display_name": "example",
      "name": "example"
    },
    "meta": {
      "request_id": "example"
    }
  }
}
```
