---
name: openalex-expert
description: Expert knowledge of OpenAlex API best practices, query patterns, and common gotchas. Use when querying OpenAlex or designing author disambiguation strategies.
---

# OpenAlex API Expert

## Three Key Rules

1. **Use IDs, not names** when filtering
2. **Two-step process**: Search to find the ID, then filter by that ID
3. **Beware of ORCID** - Although reliable in most cases, it might be wrong. It also requires verification.

## Common Mistakes to Avoid

❌ Don't filter by institution name like `?filter=institutions.display_name:Harvard`  
✅ Instead: Search for the institution first to get its ID, then filter by ID

❌ Don't mix `?search=` and `?filter=` carelessly  
✅ Use one or the other, not both together

## Useful Parameters

- `per_page=200` — Get more results (default is only 25)
- `preferred_domain` — Filter by research field
- `sample=N&seed=X` — Get random samples

## Minimal description of the author object

When you get an author object, here's what matters:
- `id`: Full URL like "https://openalex.org/A5074091984"
- `orcid`: Full URL or null
- `display_name`: Their name
- `works_count`, `cited_by_count`: How many papers and citations
- `last_known_institutions`: Where they work
- `x_concepts`: What they research (with scores)
