Execute a pre-built report

POST

/api/v1/{bucket}/reports/{report_id}/run

• Production
• Development

Runs a pre-built report against the specified bucket. The bucket is injected automatically into the SQL template. Additional parameters (dates, field names, etc.) are passed in the request body and validated before execution.

Authorizations

• BearerAuth
• ApiKeyAuth

Parameters

Path Parameters

bucket

required

string

/^[a-zA-Z0-9][a-zA-Z0-9\-]*$/

Flock bucket ID. The caller must have access to this bucket.

Example

example

report_id

required

string

Report identifier.

Example

payment_summary

Request Body

Report parameters. See the report definition for required fields.

object

key

additional properties

any

Examples

No parameters needed

{}

Field frequency by country

{
  "field": "country"
}

June birthdays

{
  "month": 6
}

2024 payment summary

{
  "year": 2024
}

Date range report

{
  "start_date": "2024-01-01",
  "end_date": "2025-01-01"
}

Responses

200

Report results

object

data

required

object

columns

required

Column names from the result set.

Array<string>

Example

[
  "uid",
  "first_name",
  "last_name"
]

rows

required

Result rows. Each row is an array of values matching the columns.

Array<Array>

Example

[
  [
    "abc123",
    "Jane",
    "Smith"
  ]
]

meta

required

object

report

string

bucket

string

400

Invalid request

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Example

{
  "error": {
    "code": "bad_request",
    "message": "Missing 'sql' field"
  }
}

401

Authentication required

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

403

Access denied to bucket

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Example

{
  "error": {
    "code": "forbidden",
    "message": "Access denied to bucket 'example'"
  }
}

404

Resource not found

object

error

required

object

code

required

Machine-readable error code.

string

Example

unauthorized

message

required

Human-readable error message.

string

Example

Authentication required

Example

{
  "error": {
    "code": "not_found",
    "message": "Unknown table: foo"
  }
}