POST
/
reports
curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/reports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Failed Authorizations 042022",
  "description": "Transactions that failed to authorize in April 2022",
  "schedule": "monthly",
  "schedule_enabled": true,
  "schedule_timezone": "Europe/London",
  "spec": {
    "model": "transactions",
    "params": {
      "fields": [
        "id",
        "external_identifier"
      ],
      "filters": {
        "status": [
          "authorization_failed"
        ]
      },
      "sort": [
        {
          "field": "captured_at",
          "order": "desc"
        }
      ]
    }
  }
}'
{
  "type": "report",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "merchant_account_id": "default",
  "name": "Failed Authorizations 042022",
  "creator_id": "bd5d40d1-913b-419c-bd62-84efc46e0026",
  "creator_display_name": "John Doe",
  "creator_type": "user",
  "created_at": "2013-07-16T19:23:00.000+00:00",
  "updated_at": "2013-07-16T19:23:00.000+00:00",
  "next_execution_at": "2023-01-01T00:00:00.000+00:00",
  "description": "Transactions that failed to authorize in April 2022",
  "schedule": "monthly",
  "schedule_enabled": true,
  "schedule_timezone": "<string>",
  "spec": {
    "model": "transactions",
    "params": {
      "fields": [
        "id",
        "external_identifier"
      ],
      "filters": {
        "status": [
          "authorization_failed"
        ]
      },
      "sort": [
        {
          "field": "captured_at",
          "order": "desc"
        }
      ]
    }
  },
  "latest_execution": {
    "type": "report-execution",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "created_at": "2013-07-16T19:23:00.000+00:00",
    "updated_at": "2013-07-16T19:23:00.000+00:00",
    "status": "succeeded",
    "context": {
      "reference_timestamp": "2013-07-16T19:23:00.000+00:00",
      "reference_timezone": "Europe/London"
    }
  }
}

This endpoint requires the reports.write scope.

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
name
string
required

The name of the report.

description
string | null

The description of the report.

schedule
enum<string>
default: once

Specifies the schedule of the report.

If this is a one-off report, set this value to once.

If this is a recurring report, this value should be set to the frequency by which the report will be executed. For example, a monthly schedule means that the report will be periodically executed at the start of each month.

Note that a weekly schedule means that the report will be executed at the start of every Monday.

Available options:
daily,
monthly,
once,
weekly
schedule_enabled
boolean | null

Indicates whether the report's scheduling is enabled. This value can only be set to true if this is a recurring report.

If this value is set to true, the report will be executed at the next_execution_at date and time.

If this is a recurring report and this value is set to false, executions of the report will not occur until this value is set to true.

If this value is not provided, schedule_enabled will automatically be set to false if schedule is once and set to true otherwise.

schedule_timezone
string
default: Etc/UTC

The time zone in which the report's executions will be scheduled. This value is used to compute the report's next_execution_at value and is only relevant when this is a recurring report. This time zone is also used to calculate the timestamp range for reports that use date-time placeholders. Date-time placeholders are dynamic timestamps that change with every report execution.

This value must be set to the time zone's name as presented in the IANA time zone database. For example, to schedule reports in the time zone of New York, set this value to America/New_York.

spec
object
required

The specifications of the report.

Response

201 - application/json
type
enum<string>

The type of this resource. Is always report.

Available options:
report
id
string

The unique identifier for this report.

merchant_account_id
string

The unique ID for a merchant account.

name
string

The name of this report.

creator_id
string | null

The unique identifier for the creator of this report.

creator_display_name
string | null

The name of the creator of this report.

creator_type
enum<string> | null

The type of the creator of this report.

Available options:
user,
private_key
created_at
string

The date and time this report was created in our system.

updated_at
string

The date and time this report was last updated.

next_execution_at
string | null

The date and time this report will next be executed, provided that schedule_enabled is true. This value is null if this is a one-off report.

description
string | null

The description of this report.

schedule
enum<string>

Specifies the schedule of this report.

If this is a one-off report, this value is once.

If this is a recurring report, this value is set to the frequency by which the report will be executed. For example, a monthly schedule means that this report will be periodically executed at the start of each month.

Note that a weekly schedule means that the report is executed at the start of every Monday.

Available options:
daily,
monthly,
once,
weekly
schedule_enabled
boolean

Indicates whether this report's scheduling is enabled. This value can only be set to true if this is a recurring report.

When this value is set to true, this report will be executed at the next_execution_at date and time.

When this value is set to false, future executions of this report are paused until this value is set to true again.

schedule_timezone
string

The time zone in which the next execution will be scheduled. This value is used to calculate this report's next_execution_at value and is only relevant if this is a recurring report. This time zone is also used to calculate the timestamp range for reports that use date-time placeholders. Date-time placeholders are dynamic timestamps that change with every report execution.

spec
object

The specifications of this report.

latest_execution
object

Details of the latest execution of this report.