History & Cleanup API

Every piece of content that WPfaker generates — posts, taxonomy terms, users, and their associated media — is tracked in a dedicated history table. This tracking system serves two critical purposes: it lets you see exactly what WPfaker has created on your site, and it makes reliable cleanup possible. Without history tracking, removing test data would require guessing which content was generated and which was created manually. With it, WPfaker can precisely identify and delete only the content it created, leaving your real data untouched.

The history and cleanup endpoints documented on this page give you full programmatic access to this tracking system. You can query the history with pagination and type filtering, retrieve statistics that break down generated content by type and subtype, calculate time savings estimates, delete individual history entries or clear the entire log, clean up orphaned entries where content was deleted outside WPfaker, and perform a complete wipe of all generated content across your entire WordPress installation.

This page also covers the field detection cache endpoints, which allow you to clear WPfaker's cached analysis of custom field types. These are grouped here because cache clearing is closely related to maintenance and cleanup workflows.

TIP

For general information about authentication, error codes, and response format, see the REST API Overview. To learn about history management from a user perspective, see the History & Tracking feature guide.

Get History Entries

Retrieve a paginated list of all items that WPfaker has generated. Each entry records the WordPress item ID, the content type (post, term, or user), the specific subtype (post type or taxonomy), the generation timestamp, whether the item still exists in WordPress, and metadata about the generation options that were used.

Endpoint

GET /wp-json/wpfaker/v1/history

Query Parameters

Parameter	Type	Default	Description
`type`	string	—	Filter by content type: `post`, `term`, `user`, `comment`, or `media`
`limit`	integer	50	Number of entries per page
`offset`	integer	0	Pagination offset

Example: Get All History

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/history?limit=50&offset=0" \
  -H "X-WP-Nonce: your-nonce"

Example: Filter by Type

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/history?type=post&limit=20" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "history": [
    {
      "id": "1",
      "content_type": "post",
      "content_id": "101",
      "content_subtype": "post",
      "meta": {
        "locale": "en_US",
        "variation_profile": "random",
        "has_featured_image": true,
        "template_name": "Blog Posts"
      },
      "created_at": "2024-01-15 10:30:00",
      "content_title": "Lorem Ipsum Dolor Sit",
      "content_exists": true,
      "template_name": "Blog Posts"
    },
    {
      "id": "2",
      "content_type": "post",
      "content_id": "102",
      "content_subtype": "page",
      "meta": {
        "locale": "en_US",
        "variation_profile": "random",
        "has_featured_image": false
      },
      "created_at": "2024-01-15 10:30:01",
      "content_title": "About Us",
      "content_exists": true,
      "template_name": null
    },
    {
      "id": "3",
      "content_type": "term",
      "content_id": "15",
      "content_subtype": "category",
      "meta": {
        "locale": "de_DE"
      },
      "created_at": "2024-01-15 09:00:00",
      "content_title": null,
      "content_exists": false,
      "template_name": null
    }
  ],
  "total": 150
}

Response Fields

Field	Type	Description
`history[].id`	string	Unique history entry ID (used for deletion)
`history[].content_id`	string	The WordPress object ID (post ID, term ID, or user ID)
`history[].content_type`	string	Content type: `post`, `term`, `user`, `comment`, or `media`
`history[].content_subtype`	string	Specific type: post type slug (e.g., `post`, `page`, `property`) or taxonomy slug (e.g., `category`, `post_tag`)
`history[].meta`	object	Generation options active when this item was created (decoded from JSON)
`history[].created_at`	string	Timestamp when the item was generated
`history[].content_title`	string\|null	The current title of the WordPress content (resolved at query time)
`history[].content_exists`	boolean	Whether the WordPress item still exists. `false` means it was deleted outside WPfaker.
`history[].template_name`	string\|null	Name of the template used, extracted from `meta.template_name`
`total`	integer	Total number of matching entries (for pagination)

INFO

The content_exists field is checked in real time against the WordPress database when you query the history. An entry with content_exists: false indicates that the WordPress content was deleted through some means other than WPfaker (e.g., manually in the admin, through WP-CLI, or by another plugin). Use the Cleanup Orphaned Entries endpoint to remove these stale records.

Get Statistics

Retrieve a summary of generation statistics, broken down by content type and subtype. This endpoint provides a quick overview of how much content WPfaker has generated, how much still exists, and how much has been deleted.

Endpoint

GET /wp-json/wpfaker/v1/history/stats

Example Request

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/history/stats" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "stats": {
    "total": 250,
    "by_type": {
      "post": 150,
      "term": 75,
      "user": 25,
      "comment": 0,
      "media": 0
    },
    "by_subtype": [
      { "content_type": "post", "content_subtype": "post", "count": "100" },
      { "content_type": "post", "content_subtype": "page", "count": "30" },
      { "content_type": "post", "content_subtype": "property", "count": "20" },
      { "content_type": "term", "content_subtype": "category", "count": "50" },
      { "content_type": "term", "content_subtype": "post_tag", "count": "25" }
    ],
    "recent_activity": [
      { "date": "2024-01-15", "count": "12" },
      { "date": "2024-01-14", "count": "8" }
    ],
    "existing": {
      "post": 142,
      "term": 70,
      "user": 25,
      "comment": 0,
      "media": 0
    }
  }
}

Response Fields

Field	Type	Description
`stats.total`	integer	Total count of all items ever generated
`stats.by_type`	object	Count of items by content type (`post`, `term`, `user`, `comment`, `media`)
`stats.by_subtype`	array	Breakdown by specific post type or taxonomy. Each entry has `content_type`, `content_subtype`, and `count`.
`stats.recent_activity`	array	Daily generation counts for the last 30 days. Each entry has `date` and `count`.
`stats.existing`	object	Items that still exist in WordPress, by content type. Checked in real time against the database.

Get Time Saved Stats

Retrieve an estimate of how much time WPfaker has saved you through automated content generation. The calculation is based on the total number of items generated and an estimated time-per-item for manual creation (which varies by content type).

Endpoint

GET /wp-json/wpfaker/v1/time-saved

Example Request

bash

curl "https://yoursite.com/wp-json/wpfaker/v1/time-saved" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "time_savings": {
    "total": {
      "hours": 10,
      "minutes": 25,
      "seconds": 0,
      "total_seconds": 37500,
      "formatted": "10 hours 25 minutes",
      "formatted_short": "10h 25m"
    },
    "by_type": {
      "posts": {
        "hours": 7,
        "minutes": 30,
        "seconds": 0,
        "total_seconds": 27000,
        "formatted": "7 hours 30 minutes",
        "formatted_short": "7h 30m"
      },
      "terms": {
        "hours": 1,
        "minutes": 52,
        "seconds": 30,
        "total_seconds": 6750,
        "formatted": "1 hour 52 minutes",
        "formatted_short": "1h 52m"
      },
      "users": {
        "hours": 1,
        "minutes": 2,
        "seconds": 30,
        "total_seconds": 3750,
        "formatted": "1 hour 2 minutes",
        "formatted_short": "1h 2m"
      },
      "comments": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "total_seconds": 0,
        "formatted": "0 seconds",
        "formatted_short": "0m"
      }
    },
    "work_days_equivalent": 1.3,
    "money_saved": {
      "amount": 781.25,
      "currency": "USD",
      "hourly_rate": 75
    },
    "last_updated": "2024-01-15 10:30:00",
    "estimates_based_on": {
      "post_with_image_and_fields": "8 min",
      "post_basic": "3 min",
      "term": "1.5 min",
      "user": "2.5 min",
      "comment": "0.5 min"
    }
  }
}

The time estimates use conservative assumptions: approximately 3 minutes per basic post (8 minutes with images and custom fields), 1.5 minutes per taxonomy term, 2.5 minutes per user profile, and 0.5 minutes per comment. The money_saved calculation uses a configurable hourly rate (default $75/hour) from the plugin settings. Each time value includes both raw seconds and human-readable formatted strings.

Reset Time Savings

Reset all time savings data to zero. Use this when you want to start tracking time savings from scratch.

Endpoint

DELETE /wp-json/wpfaker/v1/time-saved

Example Request

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/time-saved" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "message": "Time savings data has been reset."
}

Delete Single History Entry

Delete a specific history entry by its ID. This removes the tracking record from WPfaker's history table. By default, this operation also deletes the associated WordPress content (post, term, or user).

Set delete_content: false to remove only the history entry while keeping the WordPress content in place.

Endpoint

DELETE /wp-json/wpfaker/v1/history/{id}

Parameters

Parameter	Type	Default	Description
`delete_content`	boolean	`true`	Also delete the actual WordPress content (post, term, or user)

Example: Delete History Entry and Content

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/history/42" \
  -H "X-WP-Nonce: your-nonce"

Example: Delete History Entry Only

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/history/42" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "delete_content": false
  }'

Response

json

{
  "success": true,
  "message": "Eintrag gelöscht",
  "entry_deleted": true,
  "content_deleted": true
}

The entry_deleted field confirms the history record was removed. The content_deleted field indicates whether the associated WordPress content was also deleted (only true when delete_content was true and the content still existed).

If the history entry is not found, the endpoint returns a 404 response:

json

{
  "success": false,
  "message": "Löschen fehlgeschlagen"
}

Clear All History

Delete all history entries from WPfaker's tracking table. This is a record-keeping operation only — it does not delete any actual WordPress content. After clearing history, WPfaker will no longer be able to identify previously generated content, which means cleanup operations will not work for items that were generated before the clear.

Endpoint

DELETE /wp-json/wpfaker/v1/history/clear

Example Request

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/history/clear" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "message": "History cleared"
}

WARNING

Clearing history removes WPfaker's ability to track and clean up previously generated content. The generated posts, terms, and users remain in WordPress but are no longer associated with WPfaker. If you want to delete the content as well, use the Delete All Generated Content endpoint first, then clear history.

Cleanup Orphaned Entries

Scan the history table for entries that reference WordPress content which no longer exists, and mark those entries as deleted. This situation arises when generated content is removed outside of WPfaker — for example, through the WordPress admin, WP-CLI, or another plugin.

Running cleanup keeps your history statistics accurate and prevents the history list from showing items that can no longer be found in WordPress.

Endpoint

POST /wp-json/wpfaker/v1/history/cleanup

Example Request

bash

curl -X POST "https://yoursite.com/wp-json/wpfaker/v1/history/cleanup" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "cleaned": 12,
  "message": "12 orphaned entries cleaned up"
}

The cleaned count tells you how many history entries were updated. A count of 0 means all tracked items still exist in WordPress.

When to Run Cleanup

Run cleanup in these situations:

After deleting generated content through the WordPress admin or WP-CLI
When the history statistics show numbers that do not match what you see in WordPress
Before generating reports or exporting data that relies on accurate history counts
As part of a regular maintenance workflow on long-running development sites

Delete All Generated Content

The nuclear option: permanently delete every piece of content that WPfaker has ever generated on the current WordPress installation. This includes all generated posts (across all post types), all generated taxonomy terms, all generated users, and all media attachments that were downloaded as featured images. The history table is also cleared after deletion.

Endpoint

DELETE /wp-json/wpfaker/v1/cleanup/all

Example Request

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/cleanup/all" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "message": "150 Posts, 75 Terms, 25 Users und 120 Medien gelöscht",
  "stats": {
    "posts": 150,
    "terms": 75,
    "users": 25,
    "media": 120
  }
}

DANGER

This endpoint permanently deletes all WPfaker-generated content from your WordPress installation. This action cannot be undone. There is no confirmation step, no trash, and no recovery mechanism. Use this only when you are certain you want a clean slate.

The deletion process works by querying both the history table and the _wpfaker_generated post meta flag, ensuring that all generated content is identified even if some items are missing from history. The response provides a detailed breakdown so you know exactly what was removed.

INFO

If you need more selective deletion — for example, removing only generated posts of a specific type while keeping generated users — use the Delete Generated Content endpoint on the Generation API instead. That endpoint supports filtering by type and post type.

Clear All Field Detection Cache

Clear WPfaker's cached field detection results for all post types. Field detection cache stores the results of both pattern-based matching and AI analysis, so clearing it forces WPfaker to re-analyze every field from scratch the next time you open a template editor or trigger generation.

Endpoint

DELETE /wp-json/wpfaker/v1/field-detections

Example Request

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/field-detections" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "message": "47 Erkennungen gelöscht",
  "deleted": 47
}

The deleted count tells you how many cached detection entries were removed.

When to Clear the Cache

Clear the field detection cache when:

You have added, removed, or renamed custom fields in your field plugin (ACF, Meta Box AIO, JetEngine, etc.)
You have installed or activated a new field plugin adapter
You have changed AI settings and want fresh AI analysis results
Field types appear incorrect in the template editor

TIP

If you only need to refresh detection for a single post type, use the post-type-specific endpoint instead. This avoids unnecessary re-analysis of post types whose fields have not changed.

Clear Field Detection Cache by Post Type

Clear the field detection cache for a specific post type only. This is more efficient than clearing the entire cache when you have made changes to fields on a single post type and do not want to force re-analysis of all other types.

Endpoint

DELETE /wp-json/wpfaker/v1/field-detections/{post_type}

Example Request

bash

curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/field-detections/property" \
  -H "X-WP-Nonce: your-nonce"

Response

json

{
  "success": true,
  "message": "12 Erkennungen für \"property\" gelöscht",
  "deleted": 12
}

The deleted count tells you how many cached detection entries were removed for the specified post type.

Deleting Content

To delete specific generated content while preserving history tracking, use the Generation API's delete endpoint rather than the cleanup endpoint. The Generation API offers more granular control, including the ability to target specific IDs, filter by type, and control whether related media, terms, and authors are removed.

bash

# Delete all generated posts
curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/generate/delete" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "post",
    "force": true
  }'

# Delete specific items by ID
curl -X DELETE "https://yoursite.com/wp-json/wpfaker/v1/generate/delete" \
  -H "X-WP-Nonce: your-nonce" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "post",
    "ids": [101, 102, 103],
    "force": true
  }'

See Generation API — Delete for the full parameter reference.

Database Schema

History entries are stored in the {prefix}_wpfaker_history table. This is an internal implementation detail, but it can be useful for debugging or for understanding how WPfaker tracks generated content.

sql

CREATE TABLE wp_wpfaker_history (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  content_type varchar(50) NOT NULL,
  content_id bigint(20) unsigned NOT NULL,
  content_subtype varchar(100) DEFAULT '',
  meta longtext,
  created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY content_type (content_type),
  KEY content_id (content_id),
  KEY content_subtype (content_subtype),
  KEY created_at (created_at)
);

In addition to the history table, WPfaker marks generated posts with a _wpfaker_generated post meta flag (set to 1). This dual-tracking approach ensures reliable identification: the history table provides structured querying and metadata, while the post meta flag serves as a fallback for cases where history entries are missing or have been cleared.

Meta JSON Structure

The meta column stores a JSON object with details about the generation options that were active when the item was created:

json

{
  "locale": "en_US",
  "variation_profile": "random",
  "has_featured_image": true,
  "custom_fields_populated": true,
  "taxonomies_assigned": ["category", "post_tag"],
  "generation_time": 1.234
}

WARNING

Modifying the history table directly may cause inconsistencies between the history records and the actual WordPress content. Always use the API endpoints for history management.

History & Cleanup API ​

Get History Entries ​

Endpoint ​

Query Parameters ​

Example: Get All History ​

Example: Filter by Type ​

Response ​

Response Fields ​

Get Statistics ​

Endpoint ​

Example Request ​

Response ​

Response Fields ​

Get Time Saved Stats ​

Endpoint ​

Example Request ​

Response ​

Reset Time Savings ​

Endpoint ​

Example Request ​

Response ​

Delete Single History Entry ​

Endpoint ​

Parameters ​

Example: Delete History Entry and Content ​

Example: Delete History Entry Only ​

Response ​

Clear All History ​

Endpoint ​

Example Request ​

Response ​

Cleanup Orphaned Entries ​

Endpoint ​

Example Request ​

Response ​

When to Run Cleanup ​

Delete All Generated Content ​

Endpoint ​

Example Request ​

Response ​

Clear All Field Detection Cache ​

Endpoint ​

Example Request ​

Response ​

When to Clear the Cache ​

Clear Field Detection Cache by Post Type ​

Endpoint ​

Example Request ​

Response ​

Deleting Content ​

Database Schema ​

Meta JSON Structure ​

History & Cleanup API

Get History Entries

Endpoint

Query Parameters

Example: Get All History

Example: Filter by Type

Response

Response Fields

Get Statistics

Endpoint

Example Request

Response

Response Fields

Get Time Saved Stats

Endpoint

Example Request

Response

Reset Time Savings

Endpoint

Example Request

Response

Delete Single History Entry

Endpoint

Parameters

Example: Delete History Entry and Content

Example: Delete History Entry Only

Response

Clear All History

Endpoint

Example Request

Response

Cleanup Orphaned Entries

Endpoint

Example Request

Response

When to Run Cleanup

Delete All Generated Content

Endpoint

Example Request

Response

Clear All Field Detection Cache

Endpoint

Example Request

Response

When to Clear the Cache

Clear Field Detection Cache by Post Type

Endpoint

Example Request

Response

Deleting Content

Database Schema

Meta JSON Structure