# FFXIV Market Board Prices Scraper (`automation-lab/ffxiv-market-board-prices-listings`) Actor

Fetch Universalis FFXIV price summaries, current listings, and recent sales by item and world, data center, or region.

- **URL**: https://apify.com/automation-lab/ffxiv-market-board-prices-listings.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.68 / 1,000 item extracteds

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?

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

## FFXIV Market Board Prices Scraper

Fetch **FFXIV market board prices** from the public Universalis API and turn them into analysis-ready records.
Give the Actor one or more Final Fantasy XIV item IDs and a world, data center, or region.
It returns one record per item with current price statistics, detailed listings, recent completed sales, quality splits, and sale velocity.

Use it for crafting-cost sheets, shopping decisions, trading research, scheduled market snapshots, and downstream data pipelines.
No Square Enix login, browser, or proxy is required.

### What this Actor does

The Actor queries Universalis for the market scope you choose:

- one world, such as `Seraph`;
- one data center, such as `Aether`;
- one region, such as `North-America` or `Europe`.

For every resolved item ID, it saves a single dataset row.
That row combines a compact price summary with configurable arrays of current listings and recent sale history.
This structure makes recurring snapshots easy to compare while preserving seller, buyer, world, quantity, quality, and timestamp detail.

### Who is it for?

- **Crafters** comparing material costs before choosing a recipe or server.
- **Traders** checking current spreads, recent sale prices, and velocity.
- **Free Company analysts** maintaining shared procurement sheets.
- **Dashboard builders** feeding FFXIV market data into a database or BI tool.
- **Automation developers** scheduling repeatable item watchlists through the Apify API.
- **Researchers** comparing item pricing across worlds, data centers, or regions.

### Why use this Actor

- Uses the public Universalis v2 JSON API directly.
- Accepts up to 100 item IDs in one run.
- Supports world, data-center, and region scopes with the same input.
- Returns current listings and recent completed sales together.
- Exposes normal-quality and high-quality statistics separately.
- Produces JSON, CSV, Excel, XML, RSS, and other Apify dataset exports.
- Uses bounded retries for temporary network, rate-limit, and upstream-server failures.
- Charges per resolved FFXIV item, not per nested listing or sale.

Universalis data is community supplied.
The Actor reports source timestamps so you can judge freshness instead of treating every value as live exchange data.

### Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `itemIds` | integer array | required | Marketable FFXIV item IDs. Maximum 100. |
| `location` | string | `North-America` | Exact Universalis world, data center, or region name. |
| `listingsLimit` | integer | `10` | Current listings included per item, from 0 to 100. |
| `historyLimit` | integer | `10` | Recent completed sales included per item, from 0 to 100. |
| `highQualityOnly` | boolean | `false` | Request only HQ market data where quality applies. |
| `maxItems` | integer | `10` | Hard cap on item IDs checked and saved, from 1 to 100. |

At least one of `listingsLimit` or `historyLimit` must be greater than zero.
Duplicate item IDs are checked only once.
Invalid locations, non-positive IDs, and unsupported limits fail with a clear error rather than returning misleading empty data.

### Finding item IDs and location names

Universalis and common FFXIV data tools expose numeric item IDs in item pages or API records.
For example, item ID `5333` is Grade 3 Thanalan Topsoil.
Use marketable IDs; currencies, quests, and other non-market entities do not have market-board data.

Location values are case-sensitive source names in normal use.
Typical values include:

- `Seraph`, `Jenova`, or another individual world;
- `Aether`, `Primal`, `Chaos`, or another data center;
- `North-America`, `Europe`, `Japan`, or `Oceania`.

A world returns that world's market.
A data center or region may contain listings and sales from multiple worlds, with `worldName` retained on each nested row.

### Getting started

1. Open the Actor input page.
2. Enter one or more numeric FFXIV item IDs.
3. Choose a world, data center, or region in `location`.
4. Set how many current listings and recent sales to include.
5. Set `maxItems` to your desired watchlist size.
6. Click **Start**.
7. Open the default dataset to inspect or export the item records.

A useful first run is:

```json
{
  "itemIds": [5333, 2],
  "location": "North-America",
  "listingsLimit": 10,
  "historyLimit": 10,
  "maxItems": 2
}
```

### Output fields

| Field | Meaning |
| --- | --- |
| `itemId` | Stable numeric FFXIV item ID. |
| `requestedLocation` | World, data center, or region supplied in the input. |
| `worldId`, `worldName` | Populated for a world-scoped response; otherwise null. |
| `dataCenter`, `region` | Source market scope when Universalis supplies it. |
| `currentAveragePrice` | Average active listing price across qualities. |
| `currentAveragePriceNq`, `currentAveragePriceHq` | NQ and HQ active-listing averages. |
| `minPrice`, `minPriceNq`, `minPriceHq` | Lowest current prices. |
| `maxPrice` | Highest current listing price in the source summary. |
| `averageSalePrice` | Average completed-sale price in source statistics. |
| `regularSaleVelocity` | Estimated daily sales across qualities. |
| `nqSaleVelocity`, `hqSaleVelocity` | NQ and HQ daily velocity estimates. |
| `listingCount` | Number of normalized listing objects included. |
| `recentSaleCount` | Number of normalized completed-sale objects included. |
| `listings` | Current price, quantity, total, quality, world, retainer, creator, and review time. |
| `recentSales` | Completed-sale price, quantity, quality, world, buyer, and sale time. |
| `lastUploadedAt` | Last market upload time reported by Universalis, when available. |
| `sourceUrl` | Exact public Universalis API request used. |
| `retrievedAt` | Time this Actor retrieved the data. |

Nullable summary fields remain `null` when Universalis does not report that statistic.
Nested malformed rows are excluded rather than emitted with invalid price or quantity values.

### Example output

This abbreviated record reflects the Actor's current output shape:

```json
{
  "itemId": 5333,
  "requestedLocation": "North-America",
  "worldId": null,
  "worldName": null,
  "dataCenter": null,
  "region": "North-America",
  "currentAveragePrice": 546.21,
  "currentAveragePriceNq": 487.35,
  "currentAveragePriceHq": 605.08,
  "minPrice": 1,
  "averageSalePrice": 520.12,
  "regularSaleVelocity": 384.4,
  "listingCount": 10,
  "recentSaleCount": 10,
  "listings": [
    {
      "listingId": "2814750591605663",
      "pricePerUnit": 1,
      "quantity": 19,
      "total": 19,
      "highQuality": false,
      "worldName": "Jenova",
      "retainerName": "Leashie",
      "lastReviewedAt": "2026-09-15T19:05:58.000Z"
    }
  ],
  "recentSales": [
    {
      "pricePerUnit": 9,
      "quantity": 1,
      "total": 9,
      "highQuality": false,
      "worldName": "Siren",
      "soldAt": "2026-09-15T20:28:23.000Z"
    }
  ],
  "lastUploadedAt": "2026-09-15T20:30:00.000Z",
  "retrievedAt": "2026-09-15T20:31:00.000Z"
}
```

Prices and names above are illustrative of a real response shape and naturally change as players trade.

### How much does it cost to check FFXIV market board items?

The Actor uses pay-per-event pricing:

- a one-time **$0.005 start fee** per run;
- one `item` event for each resolved FFXIV item saved.

On the BRONZE tier, each item costs **$0.006132**.
Current listings and recent sales nested under that item have no separate charge.
Unresolved item IDs do not produce or charge an item event.

| Resolved items | Calculation | Total |
| ---: | --- | ---: |
| 1 | 1 × $0.006132 + $0.005 start | 0.011132 USD |
| 10 | 10 × $0.006132 + $0.005 start | 0.066320 USD |
| 25 | 25 × $0.006132 + $0.005 start | 0.158300 USD |
| 100 | 100 × $0.006132 + $0.005 start | 0.618200 USD |

Your effective event tier depends on your Apify plan.
Platform compute is included in pay-per-event billing; check the live pricing panel for your applicable tier before a large run.

### Scheduled price monitoring

Create one Task per watchlist and schedule it hourly, daily, or weekly.
Keep the same item IDs and location so each dataset is a comparable timestamped snapshot.
Useful workflows include:

1. compare `minPrice` against the prior run;
2. track `averageSalePrice` and `regularSaleVelocity` over time;
3. alert when a crafting material crosses a target price;
4. load records into a spreadsheet or warehouse;
5. retain `lastUploadedAt` to filter stale source observations.

The Actor does not send alerts or compare prior runs itself.
Use an Apify webhook, Make, Zapier, n8n, or your own integration for those actions.

### Spreadsheet and data-pipeline integration

Every run writes to the default Apify dataset.
You can download the overview as JSON, CSV, Excel, XML, or RSS.
For tabular tools, top-level summary fields map directly to columns.
Nested `listings` and `recentSales` remain JSON arrays; flatten them in your ETL step when you need one row per listing or sale.

For a warehouse workflow:

- use `itemId` plus `retrievedAt` as snapshot identity;
- keep `requestedLocation` as a partition or dimension;
- unpack nested arrays into child tables;
- preserve `sourceUrl` and `lastUploadedAt` for lineage and freshness checks.

### Use from the Apify API with cURL

Replace `YOUR_APIFY_TOKEN` with your Apify API token:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~ffxiv-market-board-prices-listings/runs?token=YOUR_APIFY_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"itemIds":[5333,2],"location":"Aether","listingsLimit":20,"historyLimit":20,"maxItems":2}'
```

Read the resulting default dataset using the `defaultDatasetId` returned by the run.
For production code, send tokens in an authorization header rather than logging tokenized URLs.

### Use from JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/ffxiv-market-board-prices-listings').call({
  itemIds: [5333, 2, 3],
  location: 'Aether',
  listingsLimit: 20,
  historyLimit: 20,
  maxItems: 3,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use from Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/ffxiv-market-board-prices-listings').call(run_input={
    'itemIds': [5333],
    'location': 'Seraph',
    'listingsLimit': 25,
    'historyLimit': 10,
    'maxItems': 1,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with MCP and AI agents

Add the Actor to Claude Code through Apify MCP:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/ffxiv-market-board-prices-listings"
```

Claude Desktop, Cursor, and VS Code can use this equivalent MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/ffxiv-market-board-prices-listings"
    }
  }
}
```

Example prompts:

- “Check item 5333 on Seraph and summarize the cheapest current listings.”
- “Fetch items 5333, 2, and 3 across Aether with 20 recent sales each.”
- “Create a North America crafting-price snapshot and format the item summaries as a table.”

### Reliability and failure behavior

The Actor sends one bounded public-API request for the selected item batch.
It retries network timeouts, HTTP 429, and temporary HTTP 5xx failures up to three total attempts using backoff and jitter.
It does not retry stable client errors or malformed responses.

A run fails clearly when:

- `itemIds` is missing or invalid;
- both detail limits are zero;
- the location contains URL path characters;
- Universalis resolves none of the requested item IDs;
- the API remains unavailable after bounded retries;
- the source returns non-JSON or an invalid payload.

If only some IDs are unresolved, valid items are still saved and the unresolved IDs are logged.

### Limits and data freshness

- Maximum 100 requested item IDs per run.
- Maximum 100 current listings and 100 recent sales inside each item record.
- `maxItems` applies in the order item IDs are supplied.
- Universalis relies on community uploads from FFXIV clients.
- Sparse items and low-activity worlds may have no current listings or recent sales.
- Retainer, creator, and buyer names appear only when the public source exposes them.
- This Actor does not resolve item names, calculate crafting recipes, predict prices, or execute in-game trades.
- It does not maintain state between runs or generate alerts by itself.

### Responsible use and legality

This Actor accesses public Universalis API data without logging into Final Fantasy XIV.
Use it in accordance with Universalis, Apify, and applicable Square Enix terms and policies.
Do not use public player or retainer names for harassment, profiling, or attempts to identify people outside the game.
Respect reasonable schedules and avoid using repeated runs to create unnecessary source load.

Final Fantasy XIV and related names are trademarks of Square Enix Holdings Co., Ltd.
This independent Actor is not affiliated with or endorsed by Square Enix or Universalis.

### AI use, data handling, and retention

This Actor does not use AI models or send input or output to an AI provider. It sends only the requested item IDs, location, and listing/history limits to the public Universalis API.

Output can include public in-game retainer, creator, and buyer names exposed by Universalis. The Actor keeps no external cache or separate copy. Run input, datasets, and logs remain in Apify storage according to your account retention settings, and you can delete them with Apify storage controls. Logs contain operational status and source request details, not Apify tokens or other credentials.

### FAQ and troubleshooting

#### Why did my run say the item was unresolved?

The numeric ID may not be marketable, may be mistyped, or may not exist in the selected market scope.
Verify the item ID with Universalis or an FFXIV data tool and retry with a known world or data center.

#### Why are listings or sales empty?

The item may have no recent activity in that scope, the requested HQ filter may exclude available records, or community data may be stale.
Try a broader data center or region and inspect `lastUploadedAt`.

#### Why does a region record contain several world names?

Region and data-center queries aggregate participating worlds.
Each nested listing and sale preserves its `worldName`, allowing you to compare the component markets.

#### Can I enter item names instead of IDs?

Not in this version.
Numeric IDs avoid ambiguous language and naming matches and map directly to the Universalis endpoint.

#### Does `maxItems` limit nested listings and sales?

No.
It limits item records.
Use `listingsLimit` and `historyLimit` to control nested detail per item.

### Related Actors by automation-lab

- [Warframe Market Mod Prices](https://apify.com/automation-lab/warframe-market-mod-prices) for current Warframe mod orders and normalized price summaries.
- [CoinGecko Crypto Market Data](https://apify.com/automation-lab/coingecko-crypto-market-data) for scheduled cryptocurrency market snapshots and history.
- [DexScreener Token Pair Market Data](https://apify.com/automation-lab/dexscreener-token-pair-market-data) for decentralized-exchange pair pricing and liquidity data.

### Support

If a valid marketable item fails unexpectedly, include the item IDs, location, detail limits, and run URL in your Apify issue report.
Do not include an Apify token or other credentials.
Source outages and community-data gaps can be diagnosed more quickly when the exact scope and timestamp are available.

# Actor input Schema

## `itemIds` (type: `array`):

Marketable FFXIV item IDs to check, such as 5333 for Grade 3 Thanalan Topsoil. Find IDs in Garland Tools, XIVAPI, or Universalis item URLs.

## `location` (type: `string`):

Exact Universalis scope name. Examples: Seraph, Aether, North-America, Europe, Japan, Oceania.

## `listingsLimit` (type: `integer`):

Maximum current listings included inside each item record. Set to 0 to fetch sale history only.

## `historyLimit` (type: `integer`):

Maximum recent sale-history entries included inside each item record. Set to 0 to fetch listings only.

## `highQualityOnly` (type: `boolean`):

Ask Universalis to return only high-quality listings and sales where the item supports quality variants.

## `maxItems` (type: `integer`):

Hard limit on requested item IDs checked and saved in this run.

## Actor input object example

```json
{
  "itemIds": [
    5333,
    2
  ],
  "location": "North-America",
  "listingsLimit": 10,
  "historyLimit": 10,
  "highQualityOnly": false,
  "maxItems": 10
}
```

# Actor output Schema

## `overview` (type: `string`):

Default dataset view with one record per checked FFXIV item.

# 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 = {
    "itemIds": [
        5333,
        2
    ],
    "location": "North-America",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/ffxiv-market-board-prices-listings").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 = {
    "itemIds": [
        5333,
        2,
    ],
    "location": "North-America",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/ffxiv-market-board-prices-listings").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 '{
  "itemIds": [
    5333,
    2
  ],
  "location": "North-America",
  "maxItems": 10
}' |
apify call automation-lab/ffxiv-market-board-prices-listings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/ffxiv-market-board-prices-listings"
        }
    }
}
```

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/MSckl8pRwGJfDZ4UP/builds/cDtZdbINCqGlqThqB/openapi.json