# TNL Intelligence (`theneuralledger/tnl-intelligence`) Actor

Evidence-first geopolitical, economic, supply-chain, asset exposure, and consequential-news intelligence with citations from The Neural Ledger.

- **URL**: https://apify.com/theneuralledger/tnl-intelligence.md
- **Developed by:** [The Neural Ledger](https://apify.com/theneuralledger) (community)
- **Categories:** AI, Developer tools, News
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TNL Intelligence Actor

Run cited TNL Intelligence search, monitoring, exposure, and research workflows
on Apify. The Actor uses the public TNL API and MCP service; it does not scrape
The Neural Ledger website.

### What it does

Choose one operation per run:

- Search intelligence with filters and cursor pagination.
- Retrieve one intelligence item with revision and source metadata.
- List published, revised, or retracted intelligence since a timestamp.
- Find entity, asset, or impact-path exposure.
- Run one of six evidence-first TNL research workflows.
- Retrieve the cited weekly consequential-development edition.

Results are written to the default Apify dataset. Story rows preserve stable IDs,
revisions, publication/update times, canonical URLs, citations, entities, assets,
and impact paths. Research rows preserve the complete structured result and its
citations.

### Authentication

Create a TNL API key in your account at
[The Neural Ledger](https://theneuralledger.com/member). Enter it in the
**TNL API key** field. The field is marked as an Apify secret. The Actor never
writes the key to datasets, key-value stores, or logs.

Do not put a key into a public task, README, source file, or unmasked environment
variable. Revoke the key immediately if it is ever exposed.

### Input examples

#### Search intelligence

```json
{
  "operation": "search_intelligence",
  "apiKey": "YOUR_TNL_API_KEY",
  "query": "supply-chain disruptions affecting semiconductor manufacturing",
  "pageSize": 20,
  "includeBody": false
}
```

#### Run cited research

```json
{
  "operation": "run_research",
  "apiKey": "YOUR_TNL_API_KEY",
  "workflowId": "operational-risk",
  "question": "What changed in Red Sea shipping risk and which operations are exposed?",
  "depth": "standard"
}
```

Only fields used by the selected operation are sent to TNL. Keep `pageSize`
between 1 and 100. Use ISO 8601 timestamps for all date fields.

### Output

Page operations create one dataset row per intelligence item. The `OUTPUT`
record in the default key-value store contains the operation, item count,
completion time, and the next pagination cursor when one is available.

Research operations create one dataset row containing a concise summary,
research status, citations, and the complete structured result in `payload`.

### Limits and errors

Your TNL subscription controls available scopes, quotas, and research access.
The Actor retries temporary MCP failures once. Invalid/revoked credentials,
quota exhaustion, invalid inputs, and unavailable upstream services produce
sanitized errors that do not echo credentials or upstream response bodies.

### Privacy and support

The Actor sends the fields needed for the selected operation and the API key to
TNL over HTTPS. Apify stores run input and output according to the storage and
retention settings of the Apify account that starts the run. Review the
[TNL Privacy Policy](https://theneuralledger.com/privacy) and
[TNL Terms](https://theneuralledger.com/terms).

For support, use the
[TNL Intelligence GitHub issue tracker](https://github.com/bekirdag/tnl-intelligence/issues)
or contact `tnladmin@theneuralledger.com`. Security reports should follow the
[security policy](https://github.com/bekirdag/tnl-intelligence/security/policy).

### Source and license

Source: [bekirdag/tnl-intelligence](https://github.com/bekirdag/tnl-intelligence)

License: MIT

# Actor input Schema

## `apiKey` (type: `string`):

Your TNL API key. Apify stores this value as a masked secret and the Actor never writes it to logs or outputs.

## `operation` (type: `string`):

The TNL Intelligence workflow to execute.

## `query` (type: `string`):

Required for Search intelligence.

## `id` (type: `string`):

Required for Get intelligence item.

## `since` (type: `string`):

ISO 8601 timestamp required for List recent changes.

## `kind` (type: `string`):

Required for Get exposure.

## `value` (type: `string`):

Entity, asset ticker, or impact-path identifier.

## `from` (type: `string`):

Optional ISO 8601 start timestamp.

## `to` (type: `string`):

Optional ISO 8601 end timestamp.

## `category` (type: `string`):

Optional TNL category filter.

## `geography` (type: `string`):

Optional geography filter.

## `entity` (type: `string`):

Optional entity filter for search.

## `asset` (type: `string`):

Optional asset filter for search.

## `impactPath` (type: `string`):

Optional impact-path filter for search.

## `pageSize` (type: `integer`):

Number of results to return, from 1 to 100.

## `cursor` (type: `string`):

Optional cursor returned by a previous run.

## `includeBody` (type: `boolean`):

Include the full story body when the account and endpoint permit it.

## `workflowId` (type: `string`):

Required for Run research.

## `question` (type: `string`):

Required for Run research. Use a specific, bounded question.

## `asOf` (type: `string`):

Optional research evidence boundary in ISO 8601 format.

## `depth` (type: `string`):

Evidence and analysis depth.

## `storyIds` (type: `array`):

Optional story IDs to constrain research.

## `entities` (type: `array`):

Optional entity names or IDs for research.

## `assets` (type: `array`):

Optional asset names or tickers for research.

## `weekEnding` (type: `string`):

Optional ISO 8601 end timestamp for Get weekly edition.

## Actor input object example

```json
{
  "operation": "search_intelligence",
  "query": "What changed in global energy markets?",
  "pageSize": 20,
  "includeBody": false,
  "depth": "standard"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

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

No description

# 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 = {
    "query": "What changed in global energy markets?"
};

// Run the Actor and wait for it to finish
const run = await client.actor("theneuralledger/tnl-intelligence").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 = { "query": "What changed in global energy markets?" }

# Run the Actor and wait for it to finish
run = client.actor("theneuralledger/tnl-intelligence").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "query": "What changed in global energy markets?"
}' |
apify call theneuralledger/tnl-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=theneuralledger/tnl-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/pznqfTmQldCm9d6yx/builds/4LGylsKIL7QEu4y3H/openapi.json