Instructions to Export Usage Data

10 min

Jobs to export data can be configured by calling the Jobs API.

API Endpoints

Method	Endpoint	Description
GET	https://app.amberflo.io/jobs	List all jobs
GET	https://app.amberflo.io/jobs/{id}	Get a job by ID
POST	https://app.amberflo.io/jobs	Create a job
PUT	https://app.amberflo.io/jobs	Update a job
DELETE	https://app.amberflo.io/jobs/{id}	Delete a job by ID
POST	https://app.amberflo.io/jobs/check	Validate a job without creating

All endpoints require the X-API-KEY header for authentication.

Required Fields

Field	Description
jobName	Unique name (alphanumeric, hyphens, spaces, commas, parentheses only)
s3Url	S3 bucket/path where exported data will be written
format	Output format: json, csv, or ndjson
aggregationBucket	Time granularity: hour, day, week, or month
range	Lookback window in format ago(#x) where # is a positive integer and x is d (days), h (hours), or m (minutes). Example: ago(7d)

Scheduling (pick one)

Field	Description
cron	Standard 5-field cron expression for recurring execution (e.g. /5 * * *)
scheduledTimeInSeconds	Unix epoch timestamp (seconds) for a one-off execution

See https://crontab.guru/ for constructing cron expression.

Note: cron and scheduledTimeInSeconds are mutually exclusive. Provide one or neither.

Optional Fields

Field	Default	Description
description	null	Human-readable description
email	null	Notification email address
enabled	true	Whether the job is active
sparse	true	Return sparse query results
minimizeFresh	true	Minimize fresh data in results
endTimeOffset	null	End time offset in ago(#x) format
meterApiNames	null	Array of meter API names to query
groupBy	null	Array of dimensions to group by
filter	null	Object mapping dimension names to arrays of allowed values
rescaleFunction	null	Object with function (multiply) and coefficient (number)

Create a Job

curl -X POST https://app.amberflo.io/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
    "jobName": "Daily export",
    "s3Url": "my-usage-bucket",
    "format": "csv",
    "aggregationBucket": "day",
    "range": "ago(7d)",
    "cron": "0 2 * * *",
    "enabled": true,
    "meterApiNames": ["api_calls", "storage"],
    "groupBy": ["customer_id"],
    "filter": {
      "region": ["us-east-1", "eu-west-1"]
    }
  }'

Update a Job

curl -X PUT https://app.amberflo.io/jobs \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
    "id": "<JOB_ID>",
    "jobName": "Daily export",
    "s3Url": "my-usage-bucket",
    "format": "csv",
    "aggregationBucket": "day",
    "range": "ago(7d)",
    "cron": "0 3 * * *",
    "enabled": true
  }'

Delete a Job

curl -X DELETE https://app.amberflo.io/jobs/<JOB_ID> \
  -H "X-API-KEY: <YOUR_API_KEY>"

Validate a Job (dry run)

curl -X POST https://app.amberflo.io/jobs/check \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{
    "jobName": "Daily export",
    "s3Url": "my-usage-bucket",
    "format": "csv",
    "aggregationBucket": "day",
    "range": "ago(7d)",
    "cron": "0 2 * * *"
  }'

Validation

Use POST /jobs/check to validate a job configuration without creating it. It returns the validated job and the query that would be built.

S3 Bucket Permissions

The user must grant Amberflo cross-account write access to their S3 bucket. The only permission required is s3:PutObject.

Add a bucket policy like:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AMBERFLO_ACCOUNT_ID>:root"
      },
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::<CUSTOMER_BUCKET>/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-acl": "bucket-owner-full-control"
        }
      }
    }
  ]
}

Objects are written with the bucket-owner-full-control ACL so the customer retains full ownership of the files in their bucket. No read, list, or delete permissions are needed.