openapi: 3.2.0 info: title: Gr4vy Insights API description: The Gr4vy API. version: 1.0.0 tags: - name: Insights description: Retrieve Insights data. paths: /metrics-explorer/{source}/metrics/{metric}/modules/{module}: get: tags: - Insights summary: Get module's data description: 'Retrieves the data for a module. The data to be used depends on `source`. **Important:** The currency filter query parameter is **required** when the `metric` is set to `volume`.' operationId: get_metrics_explorer_module security: - OAuth2PasswordBearer: - metrics-explorer.read parameters: - name: source in: path required: true schema: $ref: '#/components/schemas/MetricsExplorerSource' description: Source of the data examples: - authentication - authorization description: Source of the data - name: metric in: path required: true schema: $ref: '#/components/schemas/MetricsExplorerMetric' description: The metric to be calculated examples: - transactions description: The metric to be calculated - name: module in: path required: true schema: $ref: '#/components/schemas/MetricsExplorerModule' description: Module for which to retrieve data examples: - country description: Module for which to retrieve data - name: datetime_range in: query required: true schema: type: string description: 'Filters the results to the set of data aggregated over the duration of the specified period. This parameter should be in the format of [ISO 8601 interval](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) while the duration only format is not accepted. Start and end are either a datetime in ISO 8601 format or a placeholder which is one of the following: `now`, `hour_start` and `hour_end`.' examples: - 2025-01-01T00:00:00/P7D title: Datetime Range description: 'Filters the results to the set of data aggregated over the duration of the specified period. This parameter should be in the format of [ISO 8601 interval](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) while the duration only format is not accepted. Start and end are either a datetime in ISO 8601 format or a placeholder which is one of the following: `now`, `hour_start` and `hour_end`.' - name: authentication_outcome in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions whose authentication process ended with the specified outcome. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo an authentication process. examples: - abandoned title: Authentication Outcome description: Filters the results to only include transactions whose authentication process ended with the specified outcome. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo an authentication process. - name: authorized in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were authorized (1) or declined (0). examples: - '1' title: Authorized description: Filters the results to only include transactions that were authorized (1) or declined (0). - name: country in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - GB title: Country description: Filters the results to only include transactions that were processed in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: currency in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed in the specified currency. The currency code should be in the ISO 4217 format.
**Important:** This query parameter is **required** when the `metric` is set to `volume`. examples: - GBP title: Currency description: Filters the results to only include transactions that were processed in the specified currency. The currency code should be in the ISO 4217 format.
**Important:** This query parameter is **required** when the `metric` is set to `volume`. - name: error_code in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that failed with the specified error code. The error code is a string that describes the reason for the failure. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - invalid_credentials title: Error Code description: Filters the results to only include transactions that failed with the specified error code. The error code is a string that describes the reason for the failure. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: instrument_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that used the specified instrument type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - network_token title: Instrument Type description: Filters the results to only include transactions that used the specified instrument type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: is_subsequent_payment in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that are subsequent payments. A subsequent payment is a payment that is made after an initial payment, typically in a subscription or recurring payment scenario. The value should be either "0" (false) or "1" (true). examples: - '0' - '1' title: Is Subsequent Payment description: Filters the results to only include transactions that are subsequent payments. A subsequent payment is a payment that is made after an initial payment, typically in a subscription or recurring payment scenario. The value should be either "0" (false) or "1" (true). - name: liability_shifted in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions where liability was shifted (1) or was not shifted (0). examples: - '0' - '1' title: Liability Shifted description: Filters the results to only include transactions where liability was shifted (1) or was not shifted (0). - name: merchant_initiated in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were initiated by the merchant. The value should be either "0" (false) or "1" (true). examples: - '0' - '1' title: Merchant Initiated description: Filters the results to only include transactions that were initiated by the merchant. The value should be either "0" (false) or "1" (true). - name: metadata in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that have the specified metadata. The metadata should be in JSON format and contain a single key-value pair. examples: - key: value title: Metadata description: Filters the results to only include transactions that have the specified metadata. The metadata should be in JSON format and contain a single key-value pair. - name: method in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed using the specified payment method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - card title: Method description: Filters the results to only include transactions that were processed using the specified payment method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_bin in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that used the specified payment method bin. The payment method bin is the first 6 digits of the card number. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - '123456' title: Payment Method Bin description: Filters the results to only include transactions that used the specified payment method bin. The payment method bin is the first 6 digits of the card number. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_card_issuer_name in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified card issuer name. The card issuer name is the name of the bank or financial institution that issued the card used for the transaction. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - Barclays title: Payment Method Card Issuer Name description: Filters the results to only include transactions that were processed with the specified card issuer name. The card issuer name is the name of the bank or financial institution that issued the card used for the transaction. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_card_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that used the specified card type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - credit - debit - prepaid title: Payment Method Card Type description: Filters the results to only include transactions that used the specified card type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_country in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with a card issued in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - GB title: Payment Method Country description: Filters the results to only include transactions that were processed with a card issued in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_scheme in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified payment method scheme. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - visa title: Payment Method Scheme description: Filters the results to only include transactions that were processed with the specified payment method scheme. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_service_id in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified payment service ID. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - 06319aec-2c0f-4c7b-8af1-047ca037fc021 title: Payment Service Id description: Filters the results to only include transactions that were processed with the specified payment service ID. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_source in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified payment source. examples: - ecommerce - recurring title: Payment Source description: Filters the results to only include transactions that were processed with the specified payment source. - name: raw_response_code in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that received the specified raw response code from the payment service. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - COMPLETED title: Raw Response Code description: Filters the results to only include transactions that received the specified raw response code from the payment service. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: rule_id_route_transaction in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified routing rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any routing rule. examples: - c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 title: Rule Id Route Transaction description: Filters the results to only include transactions that were processed with the specified routing rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any routing rule. - name: rule_id_skip_3ds in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified 3DS rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any 3DS rule. examples: - c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 title: Rule Id Skip 3Ds description: Filters the results to only include transactions that were processed with the specified 3DS rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any 3DS rule. - name: rule_variant_id in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified split routing rule outcome variant. The variant ID should be in UUID format. examples: - 9897134a-fd29-4b0f-9391-a5cf965f0859 title: Rule Variant Id description: Filters the results to only include transactions that were processed with the specified split routing rule outcome variant. The variant ID should be in UUID format. - name: three_d_secure_auth_resp in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that received the specified response during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - Y title: Three D Secure Auth Resp description: Filters the results to only include transactions that received the specified response during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: three_d_secure_eci in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that received the specified ECI during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - '05' title: Three D Secure Eci description: Filters the results to only include transactions that received the specified ECI during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: three_d_secure_method in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that underwent 3DS authentication with the specified method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo 3DS authentication. examples: - challenge - frictionless title: Three D Secure Method description: Filters the results to only include transactions that underwent 3DS authentication with the specified method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo 3DS authentication. - name: x-gr4vy-merchant-account-id in: header required: false schema: anyOf: - type: string - type: 'null' description: The ID of the merchant account to use for this request. examples: - default title: X-Gr4Vy-Merchant-Account-Id description: The ID of the merchant account to use for this request. responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/ModuleResponse' title: Response Get Metrics Explorer Module '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: The request was unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: The credentials were invalid or the caller did not have permission to act on the resource. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: The resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error404' '405': description: The request method was not allowed. content: application/json: schema: $ref: '#/components/schemas/Error405' '409': description: A duplicate record was found. content: application/json: schema: $ref: '#/components/schemas/Error409' '425': description: The request was too early. content: application/json: schema: $ref: '#/components/schemas/Error425' '429': description: Too many requests were made. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error500' '502': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error502' '504': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error504' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-speakeasy-ignore: true /metrics-explorer/{source}/metrics/{metric}/totals: get: tags: - Insights summary: Get totals data description: 'Retrieves the data for the line chart and summary. The data to be used depends on `source`. **Important:** The currency filter query parameter is **required** when the `metric` is set to `volume`.' operationId: get_metrics_explorer_totals security: - OAuth2PasswordBearer: - metrics-explorer.read parameters: - name: source in: path required: true schema: $ref: '#/components/schemas/MetricsExplorerSource' description: Source of the data examples: - authentication - authorization description: Source of the data - name: metric in: path required: true schema: $ref: '#/components/schemas/MetricsExplorerMetric' description: The metric to be calculated examples: - transactions description: The metric to be calculated - name: datetime_range in: query required: true schema: type: string description: 'Filters the results to the set of data aggregated over the duration of the specified period. This parameter should be in the format of [ISO 8601 interval](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) while the duration only format is not accepted. Start and end are either a datetime in ISO 8601 format or a placeholder which is one of the following: `now`, `hour_start` and `hour_end`.' examples: - 2025-01-01T00:00:00/P7D title: Datetime Range description: 'Filters the results to the set of data aggregated over the duration of the specified period. This parameter should be in the format of [ISO 8601 interval](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) while the duration only format is not accepted. Start and end are either a datetime in ISO 8601 format or a placeholder which is one of the following: `now`, `hour_start` and `hour_end`.' - name: authentication_outcome in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions whose authentication process ended with the specified outcome. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo an authentication process. examples: - abandoned title: Authentication Outcome description: Filters the results to only include transactions whose authentication process ended with the specified outcome. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo an authentication process. - name: authorized in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were authorized (1) or declined (0). examples: - '1' title: Authorized description: Filters the results to only include transactions that were authorized (1) or declined (0). - name: country in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - GB title: Country description: Filters the results to only include transactions that were processed in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: currency in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed in the specified currency. The currency code should be in the ISO 4217 format.
**Important:** This query parameter is **required** when the `metric` is set to `volume`. examples: - GBP title: Currency description: Filters the results to only include transactions that were processed in the specified currency. The currency code should be in the ISO 4217 format.
**Important:** This query parameter is **required** when the `metric` is set to `volume`. - name: error_code in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that failed with the specified error code. The error code is a string that describes the reason for the failure. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - invalid_credentials title: Error Code description: Filters the results to only include transactions that failed with the specified error code. The error code is a string that describes the reason for the failure. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: instrument_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that used the specified instrument type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - network_token title: Instrument Type description: Filters the results to only include transactions that used the specified instrument type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: is_subsequent_payment in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that are subsequent payments. A subsequent payment is a payment that is made after an initial payment, typically in a subscription or recurring payment scenario. The value should be either "0" (false) or "1" (true). examples: - '0' - '1' title: Is Subsequent Payment description: Filters the results to only include transactions that are subsequent payments. A subsequent payment is a payment that is made after an initial payment, typically in a subscription or recurring payment scenario. The value should be either "0" (false) or "1" (true). - name: liability_shifted in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions where liability was shifted (1) or was not shifted (0). examples: - '0' - '1' title: Liability Shifted description: Filters the results to only include transactions where liability was shifted (1) or was not shifted (0). - name: merchant_initiated in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were initiated by the merchant. The value should be either "0" (false) or "1" (true). examples: - '0' - '1' title: Merchant Initiated description: Filters the results to only include transactions that were initiated by the merchant. The value should be either "0" (false) or "1" (true). - name: metadata in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that have the specified metadata. The metadata should be in JSON format and contain a single key-value pair. examples: - key: value title: Metadata description: Filters the results to only include transactions that have the specified metadata. The metadata should be in JSON format and contain a single key-value pair. - name: method in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed using the specified payment method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - card title: Method description: Filters the results to only include transactions that were processed using the specified payment method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_bin in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that used the specified payment method bin. The payment method bin is the first 6 digits of the card number. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - '123456' title: Payment Method Bin description: Filters the results to only include transactions that used the specified payment method bin. The payment method bin is the first 6 digits of the card number. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_card_issuer_name in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified card issuer name. The card issuer name is the name of the bank or financial institution that issued the card used for the transaction. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - Barclays title: Payment Method Card Issuer Name description: Filters the results to only include transactions that were processed with the specified card issuer name. The card issuer name is the name of the bank or financial institution that issued the card used for the transaction. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_card_type in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that used the specified card type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - credit - debit - prepaid title: Payment Method Card Type description: Filters the results to only include transactions that used the specified card type. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_country in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with a card issued in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - GB title: Payment Method Country description: Filters the results to only include transactions that were processed with a card issued in the specified country. The country code should be in the ISO 3166-1 two letter format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_method_scheme in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified payment method scheme. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - visa title: Payment Method Scheme description: Filters the results to only include transactions that were processed with the specified payment method scheme. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_service_id in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified payment service ID. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - 06319aec-2c0f-4c7b-8af1-047ca037fc021 title: Payment Service Id description: Filters the results to only include transactions that were processed with the specified payment service ID. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: payment_source in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified payment source. examples: - ecommerce - recurring title: Payment Source description: Filters the results to only include transactions that were processed with the specified payment source. - name: raw_response_code in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that received the specified raw response code from the payment service. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - COMPLETED title: Raw Response Code description: Filters the results to only include transactions that received the specified raw response code from the payment service. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: rule_id_route_transaction in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified routing rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any routing rule. examples: - c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 title: Rule Id Route Transaction description: Filters the results to only include transactions that were processed with the specified routing rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any routing rule. - name: rule_id_skip_3ds in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified 3DS rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any 3DS rule. examples: - c2fefd1b-6ed0-4038-bbc8-48ea2fb7e9f7 title: Rule Id Skip 3Ds description: Filters the results to only include transactions that were processed with the specified 3DS rule. The rule ID should be in UUID format. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that were not processed by any 3DS rule. - name: rule_variant_id in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that were processed with the specified split routing rule outcome variant. The variant ID should be in UUID format. examples: - 9897134a-fd29-4b0f-9391-a5cf965f0859 title: Rule Variant Id description: Filters the results to only include transactions that were processed with the specified split routing rule outcome variant. The variant ID should be in UUID format. - name: three_d_secure_auth_resp in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that received the specified response during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - Y title: Three D Secure Auth Resp description: Filters the results to only include transactions that received the specified response during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: three_d_secure_eci in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that received the specified ECI during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. examples: - '05' title: Three D Secure Eci description: Filters the results to only include transactions that received the specified ECI during 3DS authentication. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that have a null for this field. - name: three_d_secure_method in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' description: Filters the results to only include transactions that underwent 3DS authentication with the specified method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo 3DS authentication. examples: - challenge - frictionless title: Three D Secure Method description: Filters the results to only include transactions that underwent 3DS authentication with the specified method. This parameter also accepts [the null character](https://en.wikipedia.org/wiki/Null_character) to include transactions that didn't undergo 3DS authentication. - name: exclude_previous in: query required: false schema: type: boolean description: If set to `true`, aggregations and data from the previous period will not be calculated nor returned. examples: - 'true' default: false title: Exclude Previous description: If set to `true`, aggregations and data from the previous period will not be calculated nor returned. - name: x-gr4vy-merchant-account-id in: header required: false schema: anyOf: - type: string - type: 'null' description: The ID of the merchant account to use for this request. examples: - default title: X-Gr4Vy-Merchant-Account-Id description: The ID of the merchant account to use for this request. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MetricsExplorerTotalResponse' '400': description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: The request was unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: The credentials were invalid or the caller did not have permission to act on the resource. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: The resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error404' '405': description: The request method was not allowed. content: application/json: schema: $ref: '#/components/schemas/Error405' '409': description: A duplicate record was found. content: application/json: schema: $ref: '#/components/schemas/Error409' '425': description: The request was too early. content: application/json: schema: $ref: '#/components/schemas/Error425' '429': description: Too many requests were made. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error500' '502': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error502' '504': description: The server encountered an error. content: application/json: schema: $ref: '#/components/schemas/Error504' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-speakeasy-ignore: true components: schemas: Error401: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `unauthorized` default: unauthorized examples: - unauthorized status: type: integer title: Status description: Always `401`. default: 401 examples: - 401 message: type: string title: Message description: A human readable message that provides more context to the error. default: No valid API authentication found examples: - No valid API authentication found details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error401 Error404: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `not_found` default: not_found examples: - not_found status: type: integer title: Status description: Always `404`. default: 404 examples: - 404 message: type: string title: Message description: A human readable message that provides more context to the error. default: The resource could not be found examples: - The resource could not be found details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error404 MetricsExplorerTotalSeriesSet: properties: current: $ref: '#/components/schemas/MetricsExplorerTotalSeries' description: Metrics for the transactions created during the current period aggregated by minute, hour, day or thirty days, depending on the length of the requested period. The meaning of the values depends on the metric used to call the endpoint. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. `null`s may be returned when there is no data for authorization rate to indicate that the metric is not applicable for the given time period. examples: - first_interval: 2025-03-25T00:00:00Z/PT1H values: - 100 - 200 - 300 previous: anyOf: - $ref: '#/components/schemas/MetricsExplorerTotalSeries' - type: 'null' description: Metrics for the transactions created during the period immediately preceding the current period aggregated by minute, hour, day or thirty days, depending on the length of the requested period. The meaning of the values depends on the metric used to call the endpoint. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. `null`s may be returned when there is no data for authorization rate to indicate that the metric is not applicable for the given time period. examples: - first_interval: 2025-03-18T00:00:00Z/PT1H values: - 50 - 150 - 250 additionalProperties: false type: object required: - current - previous title: MetricsExplorerTotalSeriesSet ErrorLocation: type: string enum: - query - body - path - header - unknown title: ErrorLocation Error425: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `too_early` default: too_early examples: - too_early status: type: integer title: Status description: Always `425`. default: 425 examples: - 425 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error425 MetricsExplorerSource: type: string enum: - authentication - authorization - monitoring title: MetricsExplorerSource HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError MetricsExplorerMetric: type: string enum: - volume - transactions - auth_rate title: MetricsExplorerMetric ErrorDetail: properties: location: $ref: '#/components/schemas/ErrorLocation' description: The part of the request where the property can be found that caused the error. examples: - body pointer: anyOf: - type: string format: json-pointer - type: string title: Pointer description: A JSON pointer for the particular property that caused the error. examples: - /currency message: type: string title: Message description: A human-readdable explanation of the error. examples: - 'Unknown ISO 4217 currency code: USX' type: type: string title: Type description: The type of error that was raised for this property. examples: - value_error additionalProperties: false type: object required: - location - pointer - message - type title: ErrorDetail Error405: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `method_not_allowed` default: method_not_allowed examples: - method_not_allowed status: type: integer title: Status description: Always `405`. default: 405 examples: - 405 message: type: string title: Message description: A human readable message that provides more context to the error. default: Method Not Allowed examples: - Method Not Allowed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error405 Error429: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `too_many_requests` default: too_many_requests examples: - too_many_requests status: type: integer title: Status description: Always `429`. default: 429 examples: - 429 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error429 Error500: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `server_error` default: server_error examples: - server_error status: type: integer title: Status description: Always `500`. default: 500 examples: - 500 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error500 Error504: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `gateway_timeout` default: gateway_timeout examples: - gateway_timeout status: type: integer title: Status default: 504 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error504 Error400: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `bad_request` default: bad_request examples: - bad_request status: type: integer title: Status description: Always `400`. default: 400 examples: - 400 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error400 MetricsExplorerModule: type: string enum: - authentication_outcome - authorized - country - currency - error_code - instrument_type - is_subsequent_payment - liability_shifted - merchant_initiated - metadata - method - payment_method_bin - payment_method_card_issuer_name - payment_method_card_type - payment_method_country - payment_method_scheme - payment_service - payment_source - raw_response_code - rule_route_transaction - rule_skip_3ds - rule_variant_id - three_d_secure_auth_resp - three_d_secure_eci - three_d_secure_method title: MetricsExplorerModule ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError Error502: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `bad_gateway` default: bad_gateway examples: - bad_gateway status: type: integer title: Status description: Always `502`. default: 502 examples: - 502 message: type: string title: Message description: A human readable message that provides more context to the error. default: Request could not be processed examples: - Request could not be processed details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error502 MetricsExplorerTotalSummary: properties: value: anyOf: - type: integer - type: number - type: 'null' title: Value additionalProperties: false type: object title: MetricsExplorerTotalSummary Error409: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `duplicate_record` default: duplicate_record examples: - duplicate_record status: type: integer title: Status description: Always `409`. default: 409 examples: - 409 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] resource_id: anyOf: - type: string - type: 'null' title: Resource Id description: The ID of the conflicting resource. examples: - cdc70639-cb9c-4222-a73f-b8ce39f7821b additionalProperties: false type: object title: Error409 Error403: properties: type: type: string const: error title: Type description: Always `error`. default: error examples: - error code: type: string title: Code description: Always `forbidden` default: forbidden examples: - forbidden status: type: integer title: Status description: Always `403`. default: 403 examples: - 403 message: type: string title: Message description: A human readable message that provides more context to the error. default: Generic error examples: - Request failed validation details: items: $ref: '#/components/schemas/ErrorDetail' type: array title: Details description: A list of details that further ellaborate on the error. default: [] additionalProperties: false type: object title: Error403 MetricsExplorerTotalSeries: properties: first_interval: type: string title: First Interval description: The date and time of the first data point, represented with an ISO 8601 interval value indicating whether it is aggregated by one minute (PT1M), one hour (PT1H), one day (P1D) or thirty day (P30D) periods. The aggregation period is derived from the length of the requested `datetime_range`. examples: - 2025-03-25T00:00:00Z/P1D values: items: anyOf: - type: integer - type: number - type: 'null' type: array title: Values description: The values associated with the metric for the period. "volume" and "transactions" metrics are represented as integers, while "authorization rate" metric is represented as decimal numbers. examples: - 0.9 - 0.99 - 0.85 additionalProperties: false type: object required: - first_interval - values title: MetricsExplorerTotalSeries ModuleResponse: properties: type: type: string const: metrics-explorer.module title: Type description: Always `metrics-explorer.module`. default: metrics-explorer.module examples: - metrics-explorer.module key: type: string title: Key description: The key for the module data entry. This can be used to filter the data for other modules. examples: - 5d8444cb-bcc2-4ebb-b563-9c9e486f8876 - GBP display_name: type: string title: Display Name description: The display name for the module data entry. examples: - Stripe (US) - GBP value: anyOf: - type: integer - type: number - type: 'null' title: Value description: The value of the metric calculation for the module data entry. The type depends on the metric. examples: - 2025 - 0.99 - null metadata: anyOf: - additionalProperties: anyOf: - type: string - type: boolean type: object - type: 'null' title: Metadata description: Additional metadata for the module data entry. This is used to store additional information useful for the UI. examples: - payment_service_definition_id: stripe-card additionalProperties: false type: object required: - key - display_name title: ModuleResponse MetricsExplorerTotalResponse: properties: type: type: string const: metrics-explorer.total title: Type description: Always `metrics-explorer.total`. default: metrics-explorer.total examples: - metrics-explorer.total series: $ref: '#/components/schemas/MetricsExplorerTotalSeriesSet' description: Contains two series of data points used to build the line chart. Each series contains aggregations of data created over the duration of the specified period (e.g. `P7D/hour_start`). The `previous` series contains aggregations from the period immediately preceding the `current` series. examples: - current: first_interval: 2025-03-25T00:00:00Z/PT1H values: - 100 - 200 - 300 previous: first_interval: 2025-03-18T00:00:00Z/PT1H values: - 50 - 150 - 250 summary: $ref: '#/components/schemas/MetricsExplorerTotalSummarySet' description: A summary of the totals data. examples: - current: value: 800 delta: -200.0 previous: value: 1000 - current: value: 0.85 delta: 0.1 previous: value: 0.75 additionalProperties: false type: object required: - series - summary title: MetricsExplorerTotalResponse MetricsExplorerTotalSummarySet: properties: current: $ref: '#/components/schemas/MetricsExplorerTotalSummary' description: The total value for the current period.
For `volume` and `transactions` metrics, the value is the sum of all values in the `current` series.
For `auth_rate` metric, the value is the count of authorized transactions over the count of processed transactions for the current period. examples: - value: 1000 - value: 0.85 previous: anyOf: - $ref: '#/components/schemas/MetricsExplorerTotalSummary' - type: 'null' description: The total value for the previous period.
For `volume` and `transactions` metrics, the value is the sum of all values in the `previous` series.
For `auth_rate` metric, the value is the count of authorized transactions over the count of processed transactions for the previous period. examples: - value: 800 - value: 0.75 delta: anyOf: - type: number - type: 'null' title: Delta description: The difference between the current and previous values. Positive values indicate an increase, while negative values indicate a decrease.
For `volume` and `transactions` metrics, the value is the percentage change between the current and previous values, however, for `authorization rate` metric, the value is the absolute difference between the current and previous values. examples: - 200.0 - 0.1 additionalProperties: false type: object required: - current - previous title: MetricsExplorerTotalSummarySet securitySchemes: OAuth2PasswordBearer: type: oauth2 flows: password: scopes: embed: Shorthand for all gr4vy embed related scopes sessions.refresh: Refresh access-token anti-fraud-service-definitions.read: Read Anti Fraud Service Definitions anti-fraud-services.read: Read Anti Fraud Services api-key-pairs.read: Read API Key Pairs api-logs.read: Read API Logs apple-pay-certificates.read: Read Apple Pay Certificates audit-logs.read: Read Audit Logs bin-checker.read: Read BIN Checker buyers.read: Read Buyers buyers.billing-details.read: Read Billing Details card-scheme-definitions.read: Read Card Scheme Definitions checkout-sessions.read: Read Checkout Sessions connections.read: Read Connections digital-wallets.read: Read Digital Wallets flows.read: Read Flows gift-card-service-definitions.read: Read Gift Card Service Definitions gift-card-services.read: Read Gift Card Services gift-cards.read: Read Gift Cards merchant-accounts.read: Read Merchant Accounts payment-links.read: Read Payment Links payment-method-definitions.read: Read Payment Method Definitions payment-methods.read: Read Payment Methods payment-options.read: Read Payment Options payment-service-definitions.read: Read Payment Service Definitions payment-services.read: Read Payment Service payouts.read: Read Payouts reports.read: Read Reports roles.read: Read Roles three-ds-scenarios.read: Read 3DS Scenarios transactions.read: Read Transactions users.me.read: Read User Profile vault-forward.read: Read Vault Forward vault-forward-authentications.read: Read Vault Forward Authentications vault-forward-configs.read: Read Vault Forward Configurations vault-forward-definitions.read: Read Vault Forward Definitions webhook-subscriptions.read: Read Webhook Subscriptions business-contexts.read: Read Business Contexts health-dashboard.read: Read Health Dashboard metrics-explorer.read: Read Metrics Explorer monitoring.read: Read Monitoring reset.read: Read Reset sessions.read: Read Sessions users.read: Read Users anti-fraud-service-definitions.write: Write Anti Fraud Service Definitions anti-fraud-services.write: Write Anti Fraud Services api-key-pairs.write: Write API Key Pairs api-logs.write: Write API Logs apple-pay-certificates.write: Write Apple Pay Certificates audit-logs.write: Write Audit Logs bin-checker.write: Write BIN Checker buyers.write: Write Buyers buyers.billing-details.write: Write Billing Details card-scheme-definitions.write: Write Card Scheme Definitions checkout-sessions.write: Write Checkout Sessions connections.write: Write Connections digital-wallets.write: Write Digital Wallets flows.write: Write Flows gift-card-service-definitions.write: Write Gift Card Service Definitions gift-card-services.write: Write Gift Card Services gift-cards.write: Write Gift Cards merchant-accounts.write: Write Merchant Accounts payment-links.write: Write Payment Links payment-method-definitions.write: Write Payment Method Definitions payment-methods.write: Write Payment Methods payment-options.write: Write Payment Options payment-service-definitions.write: Write Payment Service Definitions payment-services.write: Write Payment Service payouts.write: Write Payouts reports.write: Write Reports roles.write: Write Roles three-ds-scenarios.write: Write 3DS Scenarios transactions.write: Write Transactions users.me.write: Write User Profile vault-forward.write: Write Vault Forward vault-forward-authentications.write: Write Vault Forward Authentications vault-forward-configs.write: Write Vault Forward Configurations vault-forward-definitions.write: Write Vault Forward Definitions webhook-subscriptions.write: Write Webhook Subscriptions business-contexts.write: Write Business Contexts health-dashboard.write: Write Health Dashboard metrics-explorer.write: Write Metrics Explorer monitoring.write: Write Monitoring reset.write: Write Reset sessions.write: Write Sessions users.write: Write Users tokenUrl: auth/token