This page is a centralized reference for all deprecated features in the OpenAlex API. Use it to migrate old code and avoid using features that will be removed.
Already Removed
These features have been removed from the API. Using them will cause errors.
host_venue and alternate_host_venues
Removed: These Work object properties no longer exist.
Replacement: Use primary_location and locations instead.
Migration:
- work.host_venue.display_name
+ work.primary_location.source.display_name
- work.alternate_host_venues
+ work.locations
- filter=host_venue.id:S123
+ filter=primary_location.source.id:S123
- filter=host_venue.publisher:P123
+ filter=primary_location.source.host_organization:P123
grants
Removed: The grants property on Works has been removed.
Replacement: Use funders and awards for more comprehensive funding data.
Migration:
- work.grants[0].funder
+ work.funders[0].display_name
- work.grants[0].award_id
+ work.awards[0].funder_award_id
awards entity provides detailed award information including DOIs when available.
has_ngrams filter
Removed: This filter no longer works.
Replacement: Use has_fulltext instead.
- filter=has_ngrams:true
+ filter=has_fulltext:true
Deprecated (Still Working)
These features still work but are not recommended. They will be removed in the future.
Concepts Entity
Concepts are deprecated in favor of Topics. We will continue to provide Concepts on Works, but we are not actively maintaining, updating, or providing support for them.
| Feature | Concepts | Topics |
|---|
| Count | ~65,000 | ~4,500 |
| Hierarchy | 6 levels | 4 levels (domain → field → subfield → topic) |
| Source | Microsoft Academic Graph | OpenAlex native (with CWTS) |
| Status | Deprecated | Active |
| Concepts | Topics |
|---|
work.concepts | work.topics |
work.concepts[0].id | work.primary_topic.id |
/concepts endpoint | /topics endpoint |
filter=concepts.id:C123 | filter=topics.id:T123 |
- /works?filter=concepts.id:C86803240
+ /works?filter=topics.id:T10234
x_concepts on Entities
Deprecated: The x_concepts property on Authors, Sources, and Institutions will be removed.
Replacement: Use Topics-based filtering and aggregation instead.
- author.x_concepts
+ # Use: /works?filter=authorships.author.id:A123&group_by=topics.id
last_known_institution (singular)
Deprecated: The singular last_known_institution on Authors is deprecated.
Replacement: Use last_known_institutions (plural) instead.
- author.last_known_institution
+ author.last_known_institutions[0]
/text Endpoint (Aboutness)
The /text endpoint is deprecated and not recommended for new projects.
- Using the Topics already assigned to works in OpenAlex
- Building your own classifier using OpenAlex Topics as training data
Filter Aliases (Deprecated)
These filter aliases still work but use the canonical form instead:
| Deprecated | Use Instead |
|---|
concept.id | topics.id |
concepts.id | topics.id |
x_concepts.id | topics.id |
Historical: Polite Pool
Before February 2026, OpenAlex used a “polite pool” system where you could get higher rate limits by including mailto=you@example.com in your requests.
This system has been replaced by API keys.
- The
mailto parameter is ignored
- All users need an API key (free)
- See the announcement for details
Timeline
| Feature | Status | Action Required |
|---|
host_venue | Removed | Migrate to primary_location |
grants | Removed | Migrate to funders / awards |
has_ngrams | Removed | Migrate to has_fulltext |
| Concepts | Deprecated | Migrate to Topics |
x_concepts | Deprecated | Will be removed soon |
/text endpoint | Deprecated | Not recommended |
| Polite pool | Replaced | Use API keys |
Staying Updated
For announcements about deprecations and breaking changes:
