List Audit Logs

GET

audit-logs

List the append-only audit trail

curl --request GET \
  --url https://billing.example.com/v1/audit-logs \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/audit-logs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/audit-logs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/audit-logs"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/audit-logs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "actor": "<string>",
      "action": "<string>",
      "entity_type": "<string>",
      "entity_id": "<string>",
      "status": 123,
      "request_body": "<string>",
      "ip": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Every successful configuration mutation made through the API is recorded as one audit row with the actor, the route, the entity it touched and the request payload. “Configuration” is an allowlist of resource prefixes: plans, billable-metrics, coupons, webhooks, wallets, usage-alerts, dunning-campaigns, cancel-flows, settings, team, developer, accounting, mandates, quotes and credit-notes. Any POST, PUT, PATCH or DELETE under one of those prefixes that returns 2xx is captured; money-movement and high-volume ingest routes (payments, usage events, checkout) are deliberately not on the list because they already leave their own durable records. The table is append-only: updates and deletes are rejected at the database level, so history can only be added to, never rewritten.

request_body is stored verbatim — nothing is redacted. A credential submitted to an audited route is kept in the trail: for example the access_token posted to POST /v1/accounting/connect-token/:provider appears in that entry’s request_body. Treat audit-log read access accordingly.

This is the trail for “who changed what, when”. For the financial side of the books — which postings were made — use the ledger and its transaction pages; for recorded reconciliation checks use List Reconciliation Runs.

Query Parameters

Parameter	Type	Required	Description
`entity_type`	string	No	Filter to one resource segment, e.g. `plans`, `webhooks`, `wallets`.
`entity_id`	string	No	Filter to one entity by its `:id` path parameter.
`actor`	string	No	Filter to one actor — a dashboard user id, or `api_key`.
`from`	string (date-time)	No	Only entries created at or after this RFC 3339 timestamp.
`to`	string (date-time)	No	Only entries created before this RFC 3339 timestamp (exclusive).
`limit`	integer	No	Maximum entries to return. Default `100`, max `250`; larger values are capped at `250`.
`offset`	integer	No	Number of entries to skip for pagination. Default `0`.

Results come back newest first. There is no total count in the response; page by limit/offset until a page comes back short.

Example Request

curl "https://api.recurso.dev/v1/audit-logs?entity_type=plans&from=2026-08-01T00:00:00Z&limit=2" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "2e7c4a91-6b3d-4f8e-a5c2-9d1f7b3e5a60",
      "tenant_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
      "actor": "b9071c55-0e14-4720-80f3-665613ceb7de",
      "action": "PUT /v1/plans/:id/charges",
      "entity_type": "plans",
      "entity_id": "4f8a2c6e-1d3b-4e7a-9c5f-8b0d2e4a6c19",
      "status": 200,
      "request_body": "[{\"metric_id\":\"7d2b9f41-8c3e-4a5d-b6f0-1e4a7c9d2b58\",\"charge_model\":\"per_unit\",\"amounts\":{\"INR\":{\"unit_amount\":\"0.0035\"}}}]",
      "ip": "203.0.113.42",
      "created_at": "2026-08-21T11:42:17Z"
    },
    {
      "id": "9c1e5b73-4a2f-4d6c-8e0b-3f7a9c1d5e28",
      "tenant_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
      "actor": "api_key",
      "action": "POST /v1/plans",
      "entity_type": "plans",
      "status": 201,
      "request_body": "{\"name\":\"Growth\",\"code\":\"growth-monthly\",\"interval_unit\":\"month\",\"interval_count\":1,\"amount\":499900,\"currency\":\"INR\"}",
      "ip": "198.51.100.17",
      "created_at": "2026-08-14T09:03:55Z"
    }
  ]
}

Fields

Field	Type	Description
`id`	string (uuid)	The audit entry’s id
`tenant_id`	string (uuid)	The tenant the mutation was made in
`actor`	string	Who performed the action: a dashboard user id, or `api_key` for API-key-authenticated calls
`action`	string	HTTP method plus route template, e.g. `PUT /v1/plans/:id/charges`
`entity_type`	string	First resource segment of the route (`plans`, `wallets`, …)
`entity_id`	string	The `:id` path parameter, when the route has one. Omitted on collection routes such as `POST /v1/plans`
`status`	integer	The response HTTP status. Only `2xx` mutations are recorded
`request_body`	string	The raw request payload as a string, captured verbatim (no redaction) and truncated to 4 KB with a trailing `...`. Omitted when the request had no body
`ip`	string	Client IP the request came from. Omitted when unknown
`created_at`	string (date-time)	When the mutation was recorded

Errors

Status	Code	When	Fix
`400`	`validation_failed`	`from` or `to` is not an RFC 3339 timestamp	Use the form `2026-08-01T00:00:00Z`
`401`	`unauthorized`	No `Authorization` bearer token (and no session cookie) was sent	Send `Authorization: Bearer $API_KEY`
`401`	`invalid_api_key`	A bearer token was sent but is not a valid key	Check the key in Developer keys
`401`	`key_mode_mismatch`	The key’s live/test mode does not match this API host	Use a key for the right mode — see Authentication

The spec entry for this operation declares only 200 and 401, so the playground on this page does not list the 400. The handler does return 400 validation_failed for a malformed from or to; the row above documents runtime behaviour.

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Query Parameters

entity_type

string

entity_id

string

actor

string

from

string<date-time>

limit

integer

default:100

Required range: x <= 250

offset

integer

default:0

Response

Audit entries, newest first

data

object[]

Show child attributes

List the append-only audit trail

curl --request GET \
  --url https://billing.example.com/v1/audit-logs \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/audit-logs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/audit-logs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/audit-logs"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/audit-logs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "actor": "<string>",
      "action": "<string>",
      "entity_type": "<string>",
      "entity_id": "<string>",
      "status": 123,
      "request_body": "<string>",
      "ip": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Query Parameters

Example Request

Response

Fields

Errors

Authorizations

Query Parameters

Response

​Query Parameters

​Example Request

​Response

​Fields

​Errors

Authorizations

Query Parameters

Response

Query Parameters

Example Request

Response

Fields

Errors