BioScan Museo Admin: Scan Metrics and Audit Log Endpoints

BioScan Museo records two distinct activity streams: raw scan events (every time a visitor scans or views a species) and species audit log entries (every admin action such as creating, editing, or deleting a species). Both streams are exposed as filterable JSON endpoints for dashboards, exports, and automated reporting. Both endpoints share their logic with the corresponding HTML admin pages, so any filter accepted by the UI is equally valid here. All requests must be made by an authenticated session whose user account has is_admin = True. Unauthenticated requests are redirected to the login page (HTTP 302); authenticated non-admin requests abort with HTTP 403.

GET /api/admin/metricas

Returns aggregated scan metrics for the given date range and optional filters. The response is built by build_scan_metrics_context(), which runs a set of SQL aggregation queries against the ScanEvent table. Authentication: Login required + is_admin = True. Returns 403 for authenticated non-admin users.

Query parameters

start

string

Start date of the reporting window in YYYY-MM-DD format. Defaults to 30 days before today. If start is later than end, the two values are silently swapped.

end

string

End date (inclusive) in YYYY-MM-DD format. Defaults to today (UTC). Invalid date strings fall back to the default 30-day window.

species_id

string

Filter results to a single species by its internal ID. Ignored if the species does not exist in the database.

origin

string

Filter by scan origin. Accepted values: qr, web, manual. Any other value (including empty) is ignored and treated as “all origins”.

Response

filters

object

The resolved filter values applied to this request.

Show filters fields

start

string

Effective start date as YYYY-MM-DD.

end

string

Effective end date as YYYY-MM-DD.

species_id

string

Effective species ID filter, or empty string if not applied.

origin

string

Effective origin filter, or empty string if not applied.

species_options

array

All species in the database for populating a filter dropdown. Each item contains id, qr_id, nombre_comun, and nombre_cientifico.

summary

object

Top-level aggregate metrics for the filtered window.

Show summary fields

total_scans

integer

Total number of ScanEvent rows matching the filters.

unique_users

integer

Count of distinct authenticated users (user_id IS NOT NULL) who scanned within the filtered window.

scanned_species_count

integer

Count of distinct species (species_id) that received at least one scan in the filtered window.

most_scanned_species

object | null

The species with the highest scan count. null when total_scans is 0. Contains id, qr_id, nombre_comun, nombre_cientifico, and total_scans.

ranking

array

Per-species scan breakdown, ordered by total_scans descending. Each item contains:

Field	Type	Description
`species_id`	string	Internal species ID.
`qr_id`	string	QR identifier slug.
`nombre_comun`	string	Common name.
`nombre_cientifico`	string	Scientific name.
`total_scans`	integer	Total scans for this species in the window.
`unique_users`	integer	Distinct authenticated users who scanned it.
`last_scan`	string	Timestamp of the most recent scan, formatted as `YYYY-MM-DD HH:MM`. Empty string if unavailable.

chart_data

object

Pre-formatted data arrays for rendering charts.

Show chart_data fields

daily

object

Daily scan counts spanning the full date range (zero-filled for days with no scans). Contains dates (array of YYYY-MM-DD strings) and counts (array of integers, same length).

origin

object

Scan counts grouped by origin. Contains labels (["QR", "Web", "Manual"]) and counts (array of 3 integers, always in that order). Days with no events for a given origin contribute 0.

Example

curl -s \
  -H "Cookie: session=<admin-session-cookie>" \
  "https://your-museum.example.com/api/admin/metricas?start=2024-11-01&end=2024-11-30&origin=qr"

{
  "filters": {
    "start": "2024-11-01",
    "end": "2024-11-30",
    "species_id": "",
    "origin": "qr",
    "species_options": [
      { "id": "condor-001", "qr_id": "condor-001", "nombre_comun": "Cóndor Andino", "nombre_cientifico": "Vultur gryphus" }
    ]
  },
  "summary": {
    "total_scans": 412,
    "unique_users": 87,
    "scanned_species_count": 14,
    "most_scanned_species": {
      "id": "condor-001",
      "qr_id": "condor-001",
      "nombre_comun": "Cóndor Andino",
      "nombre_cientifico": "Vultur gryphus",
      "total_scans": 58
    }
  },
  "ranking": [
    {
      "species_id": "condor-001",
      "qr_id": "condor-001",
      "nombre_comun": "Cóndor Andino",
      "nombre_cientifico": "Vultur gryphus",
      "total_scans": 58,
      "unique_users": 41,
      "last_scan": "2024-11-30 17:23"
    }
  ],
  "chart_data": {
    "daily": {
      "dates": ["2024-11-01", "2024-11-02"],
      "counts": [18, 22]
    },
    "origin": {
      "labels": ["QR", "Web", "Manual"],
      "counts": [412, 0, 0]
    }
  }
}

GET /api/admin/especies/auditoria

Returns a paginated, filterable list of species audit log entries from the SpeciesAuditLog table. Audit events are created automatically whenever a species is created, updated, deleted, or viewed by an admin. Snapshots of the species name, scientific name, and qr_id are stored at write time so that log entries remain informative even after a species is deleted. Authentication: Login required + is_admin = True. Returns 403 for authenticated non-admin users.

Query parameters

species_id

string

Filter by species internal ID. Accepted even if the species has been deleted, as long as historical log entries reference it.

action

string

Filter by action type. Accepted values: created, updated, deleted, viewed_admin. Any other value is ignored.

user_id

string

Filter by the integer user ID of the admin who performed the action. Ignored if the user does not exist.

start

string

Start date in YYYY-MM-DD format. Defaults to 30 days before today.

end

string

End date (inclusive) in YYYY-MM-DD format. Defaults to today (UTC).

page

integer

Page number for pagination. Defaults to 1. Each page contains 10 items.

Response

filters

object

Resolved filter values.

Show filters fields

species_id

string

Effective species filter, or empty string.

action

string

Effective action filter, or empty string.

user_id

string

Effective user ID filter, or empty string.

start

string

Effective start date as YYYY-MM-DD.

end

string

Effective end date as YYYY-MM-DD.

species_options

array

All current species for dropdown rendering. Each item: id, nombre_comun.

user_options

array

All admin users for dropdown rendering. Each item: id, nombre.

logs

array

Paginated list of audit log entries. Each item contains:

Field	Type	Description
`id`	integer	Audit log row ID.
`species_id`	string	Internal species ID at the time of the event.
`species_name`	string	Common name from the species record, or from the snapshot if the species was deleted.
`species_scientific_name`	string	Scientific name (same fallback logic).
`qr_id`	string	QR identifier (same fallback logic).
`action`	string	One of `created`, `updated`, `deleted`, `viewed_admin`.
`field_name`	string \| null	The specific field that changed. Populated for `updated` events; `null` for others.
`old_value`	string \| null	Previous field value. Populated for `updated` events.
`new_value`	string \| null	New field value. Populated for `updated` events.
`created_at`	string	Event timestamp formatted as `YYYY-MM-DD HH:MM:SS`.
`user_id`	integer \| null	ID of the admin who triggered the event. `null` for system-generated events.
`user_name`	string	Display name of the user, or `"Sistema"` if `user_id` is `null`.
`notes`	string \| null	Free-text note attached to the event (e.g., `"Especie creada"`, `"Especie eliminada"`).

total

integer

Total number of log entries matching the filters across all pages.

pagination

object

Pagination metadata.

Show pagination fields

page

integer

Current page number.

pages

integer

Total number of pages.

has_next

boolean

true if there is a next page.

has_prev

boolean

true if there is a previous page.

next_num

integer | null

Next page number, or null if on the last page.

prev_num

integer | null

Previous page number, or null if on the first page.

Example

curl -s \
  -H "Cookie: session=<admin-session-cookie>" \
  "https://your-museum.example.com/api/admin/especies/auditoria?action=updated&page=1&start=2024-11-01&end=2024-11-30"

{
  "filters": {
    "species_id": "",
    "action": "updated",
    "user_id": "",
    "start": "2024-11-01",
    "end": "2024-11-30",
    "species_options": [{ "id": "condor-001", "nombre_comun": "Cóndor Andino" }],
    "user_options": [{ "id": 1, "nombre": "Administrador" }]
  },
  "logs": [
    {
      "id": 47,
      "species_id": "condor-001",
      "species_name": "Cóndor Andino",
      "species_scientific_name": "Vultur gryphus",
      "qr_id": "condor-001",
      "action": "updated",
      "field_name": "descripcion",
      "old_value": "Ave carroñera.",
      "new_value": "Ave carroñera emblemática de los Andes colombianos.",
      "created_at": "2024-11-12 10:45:03",
      "user_id": 1,
      "user_name": "Administrador",
      "notes": null
    }
  ],
  "total": 1,
  "pagination": {
    "page": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false,
    "next_num": null,
    "prev_num": null
  }
}

Flask App API

TTS Service API

BioScan Museo Admin: Scan Metrics and Audit Log Endpoints

GET /api/admin/metricas

Query parameters

Response

Example

GET /api/admin/especies/auditoria

Query parameters

Response

Example

Build docs developers (and LLMs) love

Flask App API

TTS Service API

Documentation Index

​GET /api/admin/metricas

​Query parameters

​Response

​Example

​GET /api/admin/especies/auditoria

​Query parameters

​Response

​Example

Build docs developers (and LLMs) love

GET /api/admin/metricas

Query parameters

Response

Example

GET /api/admin/especies/auditoria

Query parameters

Response

Example