Book Report

This is the destructive Catalog Editing operation. After showing the latest preview and receiving confirmation, atomically persist the changes only when preview_token still matches the draft revision and Catalog state. If the Catalog changed or the preview is stale, refresh the targeted Catalog and rebuild or re-preview before asking again. After any ambiguous timeout or server failure, inspect the session with bookreport_get_catalog_edit_session before retrying: if committed, stop; if draft, re-preview as needed and obtain fresh confirmation. Returns: Catalog Owner identity, atomically committed change summaries, and safe Catalog Edit Attribution.

bookreport_commit_catalog_edit_session

Creates an empty draft Catalog Edit Session for the explicitly selected Catalog Owner. First list Editable Catalogs and copy the intended Catalog Owner Public Account ID, including when editing the Actor’s own Catalog. Creation does not change saved catalog state. Returns: The newly created empty draft Catalog Edit Session.

bookreport_create_catalog_edit_session

Creates a new draft with explicit scope: use {scope:"all"} to reverse every applied change, or {scope:"selected",change_ids:[...]} for a distinct nonempty selection. Undo creation is non-destructive. Preview the new draft, show it, and commit its latest confirmed token like any other session. Returns: Catalog Owner identity and a non-destructive draft of ordered reversal changes with stable links.

bookreport_create_catalog_edit_undo_session

Use this when account defaults matter to a Report Request or its explanation. It returns safe report settings, connected-source context, and external-access capabilities. Page-read royalty settings control temporary Kindle Unlimited royalty estimates; the KENPC fraction per estimated borrow controls borrow estimation and is unrelated to series read-through. It never returns email addresses, account IDs, API keys, OAuth IDs, cookies, tokens, or raw third-party account identifiers. To connect or manage publishing, direct sales, or advertising accounts, open [Connect Accounts](https://app.getbookreport.com/connect). To import the latest data from connected accounts, open [Update Data](https://app.getbookreport.com/update). Each page uses the Book Report account signed in to the browser. For shared data, send the link to the author whose accounts need connecting or updating. Returns: Safe report defaults, connected-source summaries, and capability flags for the authenticated account.

bookreport_get_account_context

Returns the resolved Book and Edition model used by catalog editing. Book-wide metadata lives on Books; source-specific format, distributor, language, KENPC, and contributor metadata lives on Editions. Only language, KENPC, translator, editor, and illustrator may be inferred from peer Editions in the same Book. Format and distributor are never inferred. Custom definitions and direct custom values are included, and custom values are never inferred. Omit account_id to read the normal combined catalog visible to the Actor. Supplying an account_id returned by bookreport_list_editable_catalogs selects one Editable Catalog for management. Public Account IDs are canonical uppercase. Team Access never exposes the target argument. Search fields combine with AND at the logical-Book level; an Edition filter matches a Book when any Edition matches. When Editions are included, every Edition for each matching Book is returned. Archived Books and reviewed non-book products are hidden by default. Catalog keys identify catalog objects and are not guaranteed report filter keys; use bookreport_list_filter_values for authoritative report values. Catalog discovery returns descriptive metadata; bookreport_run_report returns numeric facts. Returns: Resolved catalog metadata, stable Book and Edition keys, management state, custom definitions and values, pagination, and visibility details.

bookreport_get_catalog

Returns full detail for a draft or committed Catalog Edit Session when the Actor can still manage its Catalog Owner. Use it to inspect current status, revision, ordered canonical changes, preview state, reversal links, and safe committed attribution. This read-only management call changes nothing. Returns: Catalog Owner identity and full appropriate detail for the requested Catalog Edit Session.

bookreport_get_catalog_edit_session

Returns when Book Report last successfully updated the data for each connected account. To connect or manage publishing, direct sales, or advertising accounts, open [Connect Accounts](https://app.getbookreport.com/connect). To import the latest data from connected accounts, open [Update Data](https://app.getbookreport.com/update). Each page uses the Book Report account signed in to the browser. For shared data, send the link to the author whose accounts need connecting or updating. Your application decides how old is too old. A null timestamp means no update time is available for that account. This endpoint reads update times; it does not refresh data. Returns: Connected accounts and their last update times.

bookreport_get_account_updates

Look up one Meta ad using its stable provider ID. In a report grouped by ad, set `include_filter_key: true` and use the returned `ad_key` value. The ad must be visible in your advertising reports. Unknown or inaccessible ads return a not-found tool error. Returns saved provider details without making a live Meta request. Creative data becomes available after a successful normal import. Media URLs may expire; normal imports refresh them. Failed creative reads retain the last successful snapshot and its timestamp. Copy arrays contain configured variants. Ad-level performance does not identify which variant was shown or performed best. These are the latest imported details, not historical creatives for a report date range. Links distinguish destination URLs from Facebook posts. Returns: Latest imported ad details, with nullable creative metadata and its import timestamp.

bookreport_get_ad_details

Get read-through and earnings per reader (EPR) for your series. Each result includes series totals and per-book calculations. The books array contains one entry per series position, ordered by position. Books and editions assigned to the same position are combined. Start with a date range, for example { "range": "all_time" }. To select series, call bookreport_list_filter_values with `filter: "series"`, then copy the selected `values[].value` strings into `series`. These values are currently series titles, for example `{"series": ["Harbour mysteries"]}`. Omit `series` to include all series. Date and currency conventions match bookreport_run_report. Choose which readers to include with unit_types: free downloads (free), estimated Kindle Unlimited reads (ku), and other units such as paid sales (other). All three are included by default. scope shows the observed unit counts and which categories your request includes. The `readers` count estimates how many people entered the series at your chosen starting book, usually Book 1. Each included sale, free download, or estimated KU read of that book counts as a start. Distributors do not provide individual reader histories, so these are estimates from the activity you can observe. By default, the calculation treats a series as a funnel: readers begin at your starting book, and some continue to each later book. Read-through estimates how far readers progress through the series and where they drop off. Cumulative read-through (`readThrough`) measures the percentage who reach each book from the starting book. Book-to-book read-through (`bookToBookReadThrough`) measures the percentage who continue from the previous book. If a book has no units in the selected period, that comparison uses the previous book with units. Earnings per reader (`earningsPerReader`) estimates how much you earn, on average, as one new reader moves through the series. Each book contributes according to the proportion of readers who reach it and its average earnings per unit. If 60% reach a book that earns $3 per unit, that book contributes $1.80 per starting reader. Add those contributions across the series to get EPR. Each book's contribution is returned as `eprContribution`. Mid-series starters are units that don't fit the assumption that readers begin at your starting book and continue in order. If Book 1 has 100 units but Book 2 has 150, those extra 50 units cannot all be attributed to the 100 starts in this report. They may come from people who entered later, or who bought Book 1 before your chosen date range. The available sales data cannot tell those cases apart. By default, `include_mid_series_starters` is `false`, and those extra units are excluded from the estimate. In this example, Book 2 counts as 100 units and contributes two-thirds of its observed earnings. The reduction also carries forward to later books. This keeps EPR focused on the value of a new reader at your chosen starting book, without crediting that reader with earnings that appear to have come from elsewhere. Set it to `true` to include all observed activity for your selected unit types. Read-through can then exceed 100%, and EPR may overstate what a new reader at the starting book is worth. If your series has another entry point, use `start_from_book` to estimate the value of a reader who begins there. For example, setting it to 7 starts the calculation at Book 7 and leaves out Books 1 through 6. For a comparison within each series, add attributes: ["marketplace"]. This returns the combined Overall result followed by separate marketplace results. Set include_details to true for the observed numbers and adjustments behind each result. Read notices for missing page counts, excluded series, or estimates based on few readers. Follow rowWindow.nextOffset to get the next page. Each row keeps its complete books array; scope summarizes all selected series from the requested starting book. Returns: Series totals and ordered per-book calculations, with both read-through rates, earnings per reader, resolved settings, scope, notices, and pagination. REST and MCP return the same JSON structure.

bookreport_get_series_analytics

Lists exact destinations imported with advertising facts, their current Book or Edition link, every effective report attribute with its source, and whether the destination is excluded from reports. Omit the Catalog Owner target for the Actor’s own data. Use the returned destination string unchanged when updating it.A destination can link to a readable shared Catalog. Use its returned Catalog Owner Public Account ID to identify the linked Book, Edition, or custom attribute. Direct attributes and report exclusion belong to the importing account. Returns: A bounded page of exact Ad Destinations with current links and effective attributes.

bookreport_list_ad_destinations