On this page
The current Metaculus API requires authentication. Its official API documentation specifies Authorization: Token <token>, and community forecast access depends on your access tier. A working credential does not establish that every aggregate is available.
Checked October 6, 2026 against the official API 2.0.0 specification. Examples below explain documented request structure and hypothetical parsing behavior. We have not created a token, authenticated an account, retrieved private forecasts or submitted a prediction.
Authentication and permitted use are separate
The Terms of Use were last modified September 21, 2026. They restrict commercial use and unauthorized collection. The API's own access guidance requires a separate written agreement for commercial use and prior written permission for AI/ML training, evaluation or development. Check the permission basis for the intended project before connecting it.
Keep credentials in a server-side secret store. A tutorial should use a placeholder rather than a real token; a support screenshot or console log should not contain credentials. Publishing a request example is different from authorizing a production data integration.
Start with the posts feed
The official OpenAPI specification documents GET /api/posts/. Its feed supports filters, pagination and an optional with_cp flag. This documentation-based example is for an authorized account and use:
curl --fail --silent --show-error \
-H "Authorization: Token $METACULUS_API_TOKEN" \
-H "Accept: application/json" \
'https://www.metaculus.com/api/posts/?statuses=open&limit=20&with_cp=true'We have not executed this authenticated request. The feed envelope contains next, previous and results. Do not assume the response is a bare array or that one page represents the whole platform.
A request flag does not expand your access tier
The specification says with_cp=true requests Community Prediction data subject to the account's tier. For group posts, the feed includes CP for only the top three subquestions; the detail endpoint is needed for all subquestions within the allowed scope. Preserve question identity when handling groups.
Model authentication, retrieval success and aggregate availability separately. A successful page can contain useful question metadata without the forecast value your display expected. Explain that state rather than turning it into a failed-question label or a fabricated number.
Unavailable is not a zero probability
| Application state | Display behavior |
|---|---|
| Permitted forecast value present | Display the value with its question and source context |
| Aggregate unavailable | Show unavailable; retain accessible metadata |
| Request failed | Show retrieval failure and a bounded retry path |
| Valid empty page | Show no results for the selected filter |
This table is an application design recommendation, not a list of provider error codes. A numerical zero and a missing value must survive parsing as different states. Avoid truthiness checks that replace both with the same default.
In an invented fixture, one permitted record contains a forecast of 0 and another contains no forecast field. The first has a supplied value; the second does not. The fixture tests a parser distinction, not the actual frequency or likelihood of an event on Metaculus.
Pagination needs an explicit finish condition
Suppose an invented first page has 20 records and a continuation link, and its second page has 7 records and no continuation. That example totals 27 records. It does not establish that the provider has only 27 questions or that all were accessible to your account.
For an authorized client, validate the response envelope, retain filters and stop at the documented end of pagination. Before following a returned link, validate its host and path so credentials cannot be forwarded to an unrelated destination. Bound page count and retries; record when your own cap leaves collection incomplete.
Deduplicate using the identity relevant to the display, and keep post-to-question relationships explicit. A group is not automatically one binary question. Include retrieval time and the source's documented time values separately when assessing freshness.
Read-only collection and forecast submission differ
The specification lists separate forecast-submission endpoints. A data-display example does not test submission, scoring, bot-account permissions or a forecasting strategy. Build and verify any later mutation workflow separately with the applicable account authorization.
A useful implementation review checks secrets, response validation, absent aggregates, filter persistence, pagination termination and incomplete-collection notices. These are engineering requirements still needed for a real integration, not a claim that this guide deploys one.
See Metaculus vs Alphascope for product context. Our Kalshi API, Polymarket API and PredictIt API guides cover different provider permissions and data contracts.