1in8b Engine · the life simulation behind 1 in 8 Billion

1in8b Engine API beta

The 1in8b Engine is the life simulation behind 1 in 8 Billion, where you are born as one of the babies arriving on Earth right now, by the real share of births in 172 countries and territories, and live that one life. It connects figures from the UN, WHO and the World Bank into one model of how lives go. This API lends you that world: you cannot change it, but inside it you may do almost anything. Begin a life anywhere and in any year the world has, with any condition of birth it has; decide what the person decides; meet people of any age alive today; stop anywhere and live on. For stories, games and simulations of your own, apps, teaching and research, with a free key.

Everything here is simulated. The lives follow real statistics, but they are not the real world, real people, records or forecasts. Say so wherever you show them, above all in research.

Start

1. Write to api@1in8b.life from the address you want the key at. A free key comes back by email at once.

2. Try it first, with no code: Try the 1in8b Engine calls the engine with buttons and your key, and gives each call back as code and as a prompt for an AI. The link in your key mail opens it with the key already in.

3. Then send it with each engine call:

curl -H 'Authorization: Bearer k8b_…' 'https://1in8b.life/api/v1/life?country=NGA&year=1980&record=1'

curl -H 'Authorization: Bearer k8b_…' 'https://1in8b.life/api/v1/person?country=PER&age=70'

fetch('https://1in8b.life/api/v1/simulate?country=BRA&sex=female&by=fifth&at=20,40', { headers: { Authorization: 'Bearer k8b_…' } }).then(r => r.json())

Answers are JSON (UTF-8) and can be called from a web page (CORS) to try the engine with your key typed in; in an app, call it from your server (see Keys). Each has a meta block (the API version, the engine's version, simulated: what the lives are and are not, your plan, links to this page and the credit line) and, on engine calls, usage. An AI tool can read the whole API from /api/v1/openapi.json.

From an AI app (MCP)

Add the engine as a connector in an AI app that speaks MCP (the Model Context Protocol), such as Claude: add a custom connector with the address https://1in8b.life/mcp. When you connect, our page opens and asks for your API key once; the app then holds its own tokens for that key (we keep only their hashes, the key is not kept, and the app never sees it). Ask in your own words, and the app calls the engine for you.

Each tool call is an engine call on your key: the same units, limits and terms. The tools take the common parameters; the rest (who a person is, the lines that need care, /live, whose tokens are too large for a chat) stays in the HTTP API. Turning the key off, or writing for a new one, ends the app's connections: connect again with the new key.

For those building clients: Streamable HTTP without sessions (each POST one JSON-RPC message, answered as JSON; no stream); OAuth 2.1 with PKCE (S256) for public clients, Dynamic Client Registration (/oauth/register) and Client ID Metadata Documents; discovery at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server; access tokens last an hour, refresh tokens 90 days and are replaced at each use.

Use it in a project

• NPCs and virtual worlds: people alive now (/person) as your townspeople, with their work, family and the history they lived through; one /live call moves 10 of them a year on.
• Apps and interactive stories: /live sends each decision with the odds the world gives it. You draw the screen; the person chooses.
• AI evaluation and research: test an AI on people drawn by where people live, or compare lives under different conditions. Say that the results come from a simulation.
• Classes and history: be born in any year from 1950; each year brings the country as it was and the history that reached people.
• Every call and condition is below; AI tools can read /api/v1/openapi.json.

Without coding, with an AI

You do not need to write code. Ask the AI chat you use to make you a small page that uses the engine, then open it in your browser: a good way to learn how to build things with an AI. This guide is in every edition's language (the links at the top).

1. Get a key: write anything to api@1in8b.life; a free key comes back at once. It starts with k8b_.
2. Ask an AI: copy the text below into the AI chat you use. Do not give the AI your key.
3. Open the file: download the HTML file the AI makes and open it in your browser. A preview inside the chat may block the connection.
4. Experiment: paste your key in the box at the top, pick two countries and compare. If something goes wrong, paste the error on the screen into the AI chat and it will fix it.

The text to copy and paste

Make me one HTML file that I can open in my web browser: HTML, CSS and JavaScript all in that one file, nothing to install.
It compares simulated lives in two countries using the 1in8b Engine API (docs: https://1in8b.life/en/api/).

1. A box at the top where I paste my API key (it starts with k8b_). Use it only while the page is open; never write it into the file.
2. Two country menus filled from https://1in8b.life/api/v1/countries (no key needed): use each entry's iso3, and show name.en. An optional birth year box from 1950 to 2025; empty means today's world.
3. A "Compare" button that, for each country, calls
   https://1in8b.life/api/v1/simulate?country=ISO3&n=15
   (add &year=YYYY when a year is set) with the header Authorization: Bearer <key>
4. Each answer has "female" and "male", each with age_at_death.mean (average age at death), survival["65"] (share alive at 65), children_by_46 (average number of children by 46), at_40.working (share working at 40) and at_40.education (shares by schooling at 40). Shares are numbers from 0 to 1. Show the two countries side by side in plain English sentences and simple bar charts.
5. Under the results write: "Simulated lives from the 1in8b Engine (1in8b.life), not real people. With 15 lives of each sex the figures are rough."
6. If a call fails, show the "error" text from the answer.
My free key allows 60 life units a call and 2000 a month. This comparison uses 30 a country (60 with a birth year), so keep n at 15.

Then try:

• Ask the AI to compare one country in two years instead, for example lives born in 1960 and today.
• For one life as a story, ask it to use /api/v1/life?record=1 and show the record year by year.
• Change one thing at a time ("also show how lives end, with the names from /api/v1/causes", "make the charts clearer"): that is how building with an AI goes.

Endpoints

The engine, with a key:

Catalogs, without a key: the codes the engine's answers use and their names, so you can show them in your language.

The world lent

The world stays as it is: its odds, its events and its tables are the engine's, and no call changes them. Inside it you choose: a condition of birth you ask for (fifth, place, faith, group, disability, orientation, caste, gender) is found among the world's own births, at their real shares, never made up; a combination the world does not have, or has too rarely, is refused (400). What the person decides is yours: a policy, picks by card, or each decision yourself with /live. What happens to them is the world's.

Lives on request

The engine endpoints take these parameters, all optional:

/api/v1/life?country=KOR&seed=7&record=1, with the record cut short:

{
  "meta": {
    "kind": "life",
    "tier": "free",
    "...": "..."
  },
  "query": {
    "country": "KOR",
    "n": 1,
    "seed": 7,
    "...": "..."
  },
  "lives": [
    {
      "seed": 7,
      "country": "KOR",
      "born_year": 2026,
      "sex": "M",
      "name": "Jang Junwoo",
      "born_in_city": true,
      "education": "university",
      "education_at_25": "university",
      "jobs": [
        {
          "id": "delivery",
          "from": 22,
          "to": 23
        },
        {
          "id": "creator",
          "from": 25,
          "to": 37
        },
        {
          "id": "creator",
          "from": 40,
          "to": 44
        },
        {
          "id": "creator",
          "from": 44,
          "to": 48
        },
        {
          "id": "designer",
          "from": 51,
          "to": 60
        }
      ],
      "first_partner_age": null,
      "children": 0,
      "first_child_age": null,
      "siblings": 2,
      "moves": [],
      "age_at_death": 88,
      "cause_of_death": "can",
      "died_in": "KOR",
      "who": {
        "faith": "none",
        "group": null,
        "orientation": "straight",
        "disability": [
          "movement"
        ],
        "caste": null
      },
      "family_at_birth": {
        "parents": "mother_and_father",
        "mother_age": 29,
        "father_age": 31,
        "father_there": true,
        "older_siblings": 0,
        "family_fifth": 4
      },
      "met": [
        {
          "age": 27,
          "year": 2053,
          "kind": "economic_crisis"
        },
        {
          "age": 40,
          "year": 2066,
          "kind": "economic_crisis"
        },
        {
          "age": 48,
          "year": 2074,
          "kind": "storm",
          "severe": true,
          "near": true
        },
        {
          "age": 48,
          "year": 2074,
          "kind": "economic_crisis"
        },
        {
          "age": 68,
          "year": 2094,
          "kind": "economic_crisis"
        }
      ],
      "record": [
        [
          0,
          "You got your basic vaccinations (DTP and measles).",
          "In 2023, 84% of infants worldwide received all three doses of the DTP vaccine (WHO·UNICEF)"
        ],
        [
          1,
          "Age 1. Of the boys born in South Korea the same year as you, nearly all are still alive."
        ],
        [
          1,
          "You spent Lunar New Year with your family."
        ],
        [
          "..."
        ]
      ]
    }
  ],
  "usage": {
    "month": "2026-11",
    "unit": "life units",
    "used": 1,
    "quota": "..."
  }
}

/api/v1/simulate answers with female and male (or the one sex asked), each over the lives asked and with the seed it used: the age at death (mean and percentiles), who is still alive at 1, 5, 18, 40, 65, 80 and 90, how lives end, born in a city or not, and at 40 schooling, work, sector, income (the median national percentile, and the world's top tenth and bottom half), a home of one's own; the age of a first partner and a first child, partners by 50, children by 46, moving abroad and where to, being a refugee. met holds, for each kind of thing the lives met (as in a life's met), the share of the lives that met it at least once and the median age the first time. With by, groups holds each group's lifespan, survival to 65, children, moving abroad and causes; with at, at_ages what the living held at each age (schooling, work, income percentile, partner, children, living abroad, happiness, health, net worth in median incomes, electricity at home). Shares at an age are of the lives still alive then. With few lives the figures are rough: these are results of a model, with the uncertainty of a sample.

Side by side. With several countries (country=KOR,NGA) or worlds (years=1960,1990,today,future), or both, the answer has runs: one for each country and world, each {country, year, world, female, male} with the figures above, in the order asked (each country with each world). /api/v1/simulate?country=KOR,NGA&n=30 is the comparison of two countries in one call; /api/v1/simulate?country=IND&years=1960,1990,today&at=10 shows how childhood changed (electricity_at_home at 10 among them). Each run counts its own units.

Lives are lived at the simulation's own level, the one 1 in 8 Billion itself uses (15 and over): hard roads come at their real shares (prison, dependence, violence), and the lines that need most care leave only when you ask (sensitive, suicide). Lives are simulated: they follow the real odds, so most are ordinary, and none is a real person's.

People alive now

/api/v1/person meets someone living today: born age years ago (0 to 76; left out, drawn from the people living there by age) and lived up to today, with the policy and picks you give. The answer is where they stand (state: name, age, country, place, job, income, net worth, health, happiness, knowledge, bonds, partner, children, parents, who they are; and the family as it stands: household, who lives under the same roof and how many in all, siblings with their ages and who is still at home, the partner's work and faith, the parents' work, each child at home or not, abroad, married, at work) and their family_at_birth; ask for trace, decisions or record for the years behind them, and token=1 for a token to live on with /live.

Looking for someone: job (an id of /api/v1/jobs, or agriculture, industry, services), education (at least), partnered, children (at least), abroad, working. Each try lives one person to that age, so tries (default 10 with a search, at most 200) says how many may be met, and each counts; tries_used says how many were. Someone the world rarely has may not be found: allow more tries, or ask for less.

Generations

/api/v1/lineage?country=KOR&year=1950&generations=4 lives a family line, one family: the first life from its birth year to its end, then the life of its eldest child who grew up in it (living at its end, or past fifteen when it died), then that child's, and so on. Each child is born in the year the parent had it, in the country and the town or village where the parent lived then, into the income fifth the household had then, of the family's faith and group (found among the world's own births, never made), and into the family the parent's life gave it: its name, the parents' ages, whether the other parent was there and a parting, a mother's new partner, its brothers and sisters as they came, the years its parents and the parent's own parents died, and life at least to the age the parent's record follows it to. The parent's record leaves the child's years from fifteen to the child's own generation. A family line is the people who had children: a generation that must go on and had no child who grew up is lived again (tries, each counted in the work it does), and when none of the tries had one the line stops there (ended: no_children). A child born after today is born into the coming world, from today (future). The answer has generations, each a life as /life gives it with generation and born_to (the generation before and its age then), and tries_used; record, trace, decisions, lang, policy and pick apply to every generation, the conditions of birth to the first.

A life lived from outside

POST /api/v1/live with a JSON body. To begin: {} or the conditions (country, sex, year, future, age to begin as someone alive now, fifth, place, faith, group, disability, orientation, caste, gender, policy, pick, sensitive, suicide, seed). The life runs to its first decision. Then, each step: {"token": "...", "choose": "key"}, and as you like "focus": "key" (the year's focus), "buy": ["id"] (from the spending sheet), "until": "decision" (the default: on to the next one), "year" (to the next birthday, stopping at a decision), or an age (decisions on the way made by the policy and picks; at most 25 years a call).

To look without living on (after a reload, say): {"token": "...", "view": true} gives where the life stands and what waits, counts no units and gives the same token back.

Several lives at once (an app with many people living): {"steps": [{"token": "...", "choose": "key"}, {"token": "...", "view": true}]}, up to 10, gives results in the same order, each the answer below or its own error (error, code); each step counts one unit (a view none), and the call counts once against the calls a minute.

Each answer has state (as in /person), events (the lines of the years since the last step, [age, text]), decision (id, question, about, fact, choices with key, label, note; null when none waits), focus (now and the options), sheet (what can be spent on now: id, name, does, price_ppp, can, why), ended and death at the end, and a new token. The token holds the whole life, sealed: we keep nothing, it cannot be read or changed, and it works for 90 days. Keep it to come back later, or send the same token again with another choice to see the other road: the world's dice go on the same way from there.

With care

Some lines 1 in 8 Billion keeps on the device of the person living the life. Here they leave only when you ask: sensitive=1 for drug dependence, sexual violence (never under 15), violence at home, assisted dying, a trans life's story (and gender) and the others; suicide=1 for a suicide, as a cause and in the record, always with a help line beside it. The simulation tells them without method, place or detail, from the person's own side, with help-seeking and recovery as the usual course; keep it that way where you show them. Caste and a trans life are told the same way: from the person's own side, gaps only as the data has them, being treated worse and never who one is as what costs. The engine's own tables (its life tables, cause weights and the figures it is built on) are not served.

Sources

The engine draws on these sources. Where you show what it gives, credit “1in8b Engine (1in8b.life)”; the sources' own licences ask for their credit too.

Limits

The engine is counted in life units: one life is one unit, and a life born in a past year or into the coming world is two (it takes the engine about twice the work). A simulate call over both sexes counts the lives of each. A person met is two (born in a past year; a newborn of today is one) for each try a search allows. A live life's start is one (two as someone alive now, or in a past year or the coming world), and each step after it one. A line (/lineage) is two for each generation, with the lives lived again counted in its work. A simulate call with several runs counts each.

For a project that needs more (an app, a study, a world of your own with many people living in it), larger plans will come: a builder plan for one person or a small project and a studio plan for large ones, with more life units and calls a minute for live lives. Until then write to contact@1in8b.life.

Free for public-interest use. Research at a university or institute, teaching, nonprofits and public bodies, and journalism, used without making money, get the builder plan's size free for a year (200,000 life units a month, up to 50 lives a call on /life and 400 units on /simulate, 300 engine calls a minute). Write to contact@1in8b.life from the address your key is sent to (or will be), saying who you are and what you are making. Once we say yes, that address's key moves onto it at once, or comes on it when you ask for one; after the year, ask again.

Cache what you get. Catalogs carry an ETag (send If-None-Match for a 304) and may be kept for an hour. A call with a seed may be kept for a day; one without is new each time. Every call counts its units, also one answered from the cache, and a call that would go past the month is refused whole, without counting.

Work past the units. Some calls do far more work than their units say: a condition the world rarely has is found by drawing many births, and someone met at an age few reach is born again until one does. Such a call counts the work it did, about one unit for 400 births drawn or 100 years lived, when that is more than half again its units; ordinary calls never count more. usage.this_call says what a call counted. A call that would need more work than its plan allows a call stops with a 400 (too_much_work) and counts the work done; ask for fewer lives or tries, or fewer conditions.

Keys

• Getting one: write to api@1in8b.life; any subject, a line about what you are making is welcome. The key comes back to the address you wrote from. One key an address.
• Lost it: write again from the same address. A new key replaces the old one, which stops working; the month's use carries over.
• Turning it off: write again with “stop” in the subject; the key and its record are deleted.
• From an AI app (MCP): the app acts with your key, so its calls count as yours, against the plan and the terms. Turning the key off or getting a new one ends its connections.
• Send it as Authorization: Bearer k8b_…. It is yours alone: keep it private, and do not share or sell it. We keep only its hash, never the key.
• Keep it on your server (or in your own tools). A key built into a web page or an app people download can be read and copied, and what it is used for counts against you: its units, and the terms. For an app, call the engine from your server and pass on what your users need.
• Watched, and stopped when misused: for each key we count, for the month, the kinds of calls it makes and the options it uses (above all sensitive, suicide, who a person is, searches), not what you do with the answers. A key that seems to be used against the terms may be turned off without warning, and its address gets no new key. If you think that was a mistake, write to contact@1in8b.life.

Errors are JSON too: {"error": "...", "code": "...", "status": 400, "docs": "..."}. 400 a parameter the engine cannot take (or a condition the world does not have), 401 no key or a key it does not know, 404 no such endpoint, 405 a method the endpoint does not take (POST only on /live), 413 a body too large, 429 too many calls or the units used up. code is for programs: bad_request (a parameter), not_in_world (conditions the world does not have, or too rarely, or no one reached the age), too_much_work, plan_size (more than the plan allows a call), token and live_state (a /live token, or a step that does not fit where the life stands), key, rate (calls a minute), month (the month's units; the answer's more links to the plans for more and resets gives the day the month starts again), free_day (the free plan's day), too_many, not_found, method, too_large, unavailable.

Versions

v1 stays as it is: its paths and fields are not removed or renamed; new fields and parameters may appear, and the answers follow the engine. When meta.engine changes, the same seed may give a different life (a live token goes on as it is). The engine changes as 1 in 8 Billion does, often, and older versions are not served: to reproduce a result, keep meta.engine and the date with it, and the lives you need. A change that would break v1 comes as v2, and v1 keeps working beside it.

Terms of use

The engine, its tables and its text are ours. A key gives you access to the engine, and these terms give you the right to use what it answers as below, nothing more. Using a key means you accept them.

What you may do, freely and also commercially:

• use what the engine answers in your own works: stories, games, simulations and worlds of your own built on it, apps, bots, teaching, journalism, art; change it, translate it and mix it with your own;
• research: run lives and outlooks for a study and publish findings, charts and examples drawn from them. Research and papers must say plainly that the figures come from a simulation (the 1in8b Engine, its version and the date), that the lives are simulated and not the real world, and must not present them as measurements, official statistics or forecasts. Keep the answers you need for your own analysis; do not publish them as a dataset (see below).
• Credit “1in8b Engine (1in8b.life)” with a link where you show it, and each source's credit as its licence asks.

What you may not do:

• collect answers in bulk beyond what your work or study needs, or publish them as a collection or dataset others can download or reuse;
• copy, imitate or rebuild the engine, its tables or its text, including training or tuning a model on its answers to do what it does, or working its tables back out of many answers; or copy 1 in 8 Billion itself (its name, text, art or screens): a work of your own on the engine is welcome, a copy of ours is not;
• offer the API or its answers as a service of your own (an API, a data feed), or share, sell or lend a key; get past the limits (many keys, many addresses);
• present simulated lives or outlooks as real records, official statistics or forecasts about real people or places without saying they come from a simulation, or use them to make decisions about a real person (health, insurance, credit, work, housing, migration);
• use who a person is (faith, group, caste, orientation, gender, disability) or any other condition to rank, single out, demean or stir up hatred against a group of people, to harass anyone, or to mislead (for example political or commercial claims passed off as facts). Showing how lives differ, and how people are treated differently, as the data has it, is fine;
• present a caste as above or below another, or a trans or non-binary life as a problem, a twist or a joke; a trans man or woman is called by the name they chose and the gender they live as;
• show the lines that need care (sensitive, suicide) carelessly: no method or detail, never as an answer to trouble, a reward, a score, a choice to make or a joke, never aimed at children, and a help line near them wherever they appear;
• use them for gambling or betting with real money;
• try to break, overload or get around the service or its protections (a live token included).
• Do not present your work as ours or as endorsed by us, and do not name it so it looks like the official site. The names 1in8b Engine and 1 in 8 Billion and their pages are not licensed by these terms.

• We watch how each key is used (see Keys) and may limit, change or end access, for a key or for everyone, at any time, above all when these terms are broken.
• A plan given free for public-interest use is for the work it was asked for; using it to make money, or for other work, ends it.
• During the beta the service may be slow or briefly unavailable; it comes as it is, without warranty. The site's terms apply to everything not said here.
• Questions: contact@1in8b.life.

Privacy

We keep a count of answers by endpoint, without who asked. A key is kept only as a hash, with its plan, when it was made, the month's units, the month's counts of its calls by kind and option, and the hash of the address it was mailed to (one key an address); it is deleted when it is turned off, and the address hash of a key turned off for misuse is kept so no new key goes to it. A live life's state is in its token, with you, not with us. An AI app connected through MCP: we keep the hashes of its sign-in code (5 minutes) and tokens (an hour; 90 days for the refresh token, replaced at each use), with the key's hash, the hash of the app's id and the address it goes back to; your key is checked when you paste it and not kept, and what you ask the app stays with the app and its provider. The email you write to api@1in8b.life is answered by our server and forwarded to the operator's inbox, as other email to the site is; Cloudflare, which serves the site, handles your address to deliver and protect it, as for every page (privacy policy).