# INSPIRE-HEP Literature Monitor (`mmdincer/inspire-hep-literature-monitor`) Actor

New INSPIRE-HEP records for a saved query since the last run. Stores title, record id, dates, citation count, arXiv id, and DOI. Drops email addresses. Not affiliated with INSPIRE.

- **URL**: https://apify.com/mmdincer/inspire-hep-literature-monitor.md
- **Developed by:** [Muhammet Mustafa Dincer](https://apify.com/mmdincer) (community)
- **Features:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 query checkeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## INSPIRE-HEP Literature Monitor

Watches a saved INSPIRE-HEP literature query and reports control numbers that were not in the previous run. The sample query is `control_number:2181837 or arxiv:hep-th/9711200`. On 7 Nov 2026 that query returned two records from `https://inspirehep.net/api/literature`: control number 2181837, arXiv `2211.07478`, titled "Study of $HZZ$ anomalous couplings by angular differential cross sections", and control number 451647, arXiv `hep-th/9711200`, with DOIs `10.4310/ATMP.1998.v2.n2.a1` and `10.1023/A:1026654312961`. No customer API key is required. The request goes only to the public literature endpoint.

This Actor is not affiliated with INSPIRE, INSPIRE-HEP, or CERN.

The stored fields are the title, the INSPIRE control number, the earliest date, the preprint date, the record created and updated times, the citation count, the arXiv id, and the DOI. Author names, affiliations, abstracts, and email addresses are not stored. INSPIRE's terms allow reuse of HEP collection metadata under the CC0 waiver and do not permit downloading email addresses. An email address in a kept field is removed before the row is written. The Actor does not reconstruct an article from snippets, and it does not call `/api/accounts`, `/api/submissions`, or `/api/literature/import`.

Store actors that read INSPIRE today return a search dump. They do not keep a baseline, and they do not report which control numbers appeared after the last successful read. `parseforge/inspire-hep-scraper` lists a result event at $0.005 on the free tier. `automation-lab/inspire-hep-literature-search` lists a paper event at about $0.0045 on the free tier. `johnvc/google-scholar-api` lists a search query at $0.015 and is the research-paper neighbor with current demand. This Actor is the scheduled check: which control numbers in this saved query were not saved last time?

### Quick start

1. Keep the sample query.
2. Leave **Only new records** off. The sample prefill does that on purpose.
3. Click **Start**.

The first successful read writes one row per record with status `baseline_saved`. A second run of the same sample still writes those rows, with status `unchanged`, because the prefill does not hide a control number that was already saved. The rows are the current INSPIRE metadata. They are not invented papers.

Turn **Only new records** on when you schedule the Actor. Omitting the field is the same as turning it on. After a baseline exists, an unchanged control number stays out of the dataset and still appears in the run summary. A first successful read is always written. A control number that was not saved is `new_record`. An explicit `onlyNewRecords: true` keeps the quiet schedule. An explicit `false` always writes the current window.

Use a different **Watchlist name** to start a fresh baseline. Baselines live in the named key-value store `inspire-hep-literature-monitor-state`. The snapshot stores control numbers only, not titles and not addresses. Under limited permissions, if that store cannot be opened, the run uses the default store, finishes, and treats the look as a first baseline.

The read is one request, sorted by most recent, limited to **Max records**. The sample asks for 5, and the sample query currently matches 2. A record that falls outside that window is not reported as removed. Up to 5 queries can be checked in one run. Default memory is 512 MB, so the platform start event is one unit. A normal response returns in a few seconds.

The run does not call INSPIRE when the spending limit cannot pay for `query-checked`. An empty result, an API error, a network error, and an invalid query are not charged, and an empty or failed read does not erase a baseline already saved. A new control number that does not fit in the spending limit is not written to the dataset and is not added to the baseline. `charged` is true only when `Actor.charge()` succeeded for that row. An ignored charge, including an owner run with no price, still saves the records and leaves `charged` false. A query check that was already billed stays billed when a later new record does not fit.

### Pricing

The prices in `pricing-ppe.json` are a proposal. They are not applied on the platform from this repository.

| Event | When | Free tier |
| --- | --- | --- |
| `apify-actor-start` | The run starts. At 512 MB this is one event. | $0.0005 |
| `query-checked` | One saved query whose first page included at least one record, including a later run with no new control numbers. | $0.015 |
| `new-record` | Extra charge when a control number on that page was not in the saved baseline. The first baseline is not this event. | $0.005 |

`query-checked` copies the published tiers for the `johnvc/google-scholar-api` event "Search API query executed": free $0.015, Bronze $0.01485, Silver $0.014701, and $0.014554 from Gold through Diamond. `new-record` copies the published tiers for the `parseforge/inspire-hep-scraper` event "result": free $0.005, Bronze $0.00484, Silver $0.00468, Gold $0.00452, Platinum $0.004068, Diamond $0.003616. `apify-actor-start` is $0.0005, the start price used by the published change monitors in this account. Google Scholar's own start event is $0.00001 beside a separate setup fee, and both OpenAlex and `automation-lab/inspire-hep-literature-search` list a $0.005 start. This proposal does not add a setup event, because the code does not charge one.

Each later tier is lower than or equal to the tier before it. The platform margin in the pricing file is 20 percent. `pushData` is called without an event name, so a row is not billed twice.

### Input

- **Saved queries.** INSPIRE literature search syntax, one per line. The sample is a single line that matches two stable records.
- **Max records.** An integer from 1 to 25. The sample and the schema default are 5.
- **Only new records.** Sample prefill `false`. Schema default `true` when the field is omitted.
- **Watchlist name.** Default `default`. Letters, numbers, spaces, dots, underscores, and hyphens.

There is no API key field. Do not put an email address in the query. Addresses are stripped, and a query that is only an address is rejected.

### Output

`RUN_SUMMARY` counts baselines, unchanged records, new records, empty queries, withheld records, and warnings. The run fails when every requested query fails to produce a baseline, an unchanged read, a new record, or an empty result, and when every line was invalid. A run that stops because of the spending limit still succeeds and leaves a `not_fetched` row.

### License

Apache-2.0. INSPIRE is a high-energy physics literature service. This Actor is not affiliated with INSPIRE. The sample records are a public metadata read, not an endorsement.

# Changelog

This Actor's version history is a separate document: https://apify.com/mmdincer/inspire-hep-literature-monitor/changelog.md

# Actor input Schema

## `queries` (type: `array`):

INSPIRE literature search text, one query per line. The sample matches two public records, control number 2181837 and arXiv hep-th/9711200. Up to 5 queries.

## `maxRecords` (type: `integer`):

How many records to read from the first page of each query, most recent first. The sample asks for 5. The sample query currently matches 2. 1 to 25.

## `onlyNewRecords` (type: `boolean`):

Leave this off for the sample so a repeated run still writes the current records. Turn it on, or omit the field, to hide a control number that is already in the baseline. A first successful read is always written.

## `monitorName` (type: `string`):

Baselines are stored per watchlist. Use a new name to start over without deleting the old snapshot.

## Actor input object example

```json
{
  "queries": [
    "control_number:2181837 or arxiv:hep-th/9711200"
  ],
  "maxRecords": 5,
  "onlyNewRecords": false,
  "monitorName": "default"
}
```

# Actor output Schema

## `records` (type: `string`):

One row per control number: title, dates, citation count, arXiv id, and DOI, or why the query was not stored.

## `summary` (type: `string`):

Queries requested, baselines, new records, and the first problems.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "control_number:2181837 or arxiv:hep-th/9711200"
    ],
    "maxRecords": 5,
    "onlyNewRecords": false,
    "monitorName": "default"
};

// Run the Actor and wait for it to finish
const run = await client.actor("mmdincer/inspire-hep-literature-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": ["control_number:2181837 or arxiv:hep-th/9711200"],
    "maxRecords": 5,
    "onlyNewRecords": False,
    "monitorName": "default",
}

# Run the Actor and wait for it to finish
run = client.actor("mmdincer/inspire-hep-literature-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "control_number:2181837 or arxiv:hep-th/9711200"
  ],
  "maxRecords": 5,
  "onlyNewRecords": false,
  "monitorName": "default"
}' |
apify call mmdincer/inspire-hep-literature-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mmdincer/inspire-hep-literature-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/awMEPgt1Wu56PM5ja/builds/hdnFZtTvyTPcReHjh/openapi.json