Parallel Search API quickstart: example request/response and how to pass an objective

Most teams hit the same wall on day one: they know they need reliable web grounding for their agents, but the path from “I have an API key” to “my agent is calling Search correctly” is fuzzy. This quickstart walks through a concrete Parallel Search API request and response, and shows exactly how to pass an objective so your agents get token-dense, relevant evidence in under five seconds.

---

What the Search API actually returns

Parallel’s Search API is designed for AIs, not humans skimming SERPs. A single request returns:

• Ranked URLs
• Page titles and (when available) publish dates
• Token-dense compressed excerpts per result

Those excerpts are optimized for LLM consumption—enough evidence for reasoning, without blowing up your context window. Latency is typically under 5 seconds, synchronous, at a flat per-request cost (e.g., $0.005 for 10 results), so you can wire it in as a tool call without unpredictable token spend.

---

Core request shape

At minimum, a Search API call includes:

• objective — natural language description of what your agent is trying to accomplish
• Optional search_queries — keyword-style queries to improve recall
• Result controls like max_results
• An excerpts config to set how dense the returned snippets should be

Example: find the current OpenAI CEO and leadership changes

Below is a full curl example you can paste into your terminal.

curl https://api.parallel.ai/v1beta/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -H "parallel-beta: search-extract-2025-10-10" \
  -d '{
    "objective": "Find the current CEO of OpenAI and any recent leadership changes",
    "search_queries": [
      "OpenAI CEO",
      "OpenAI leadership 2026"
    ],
    "max_results": 5,
    "excerpts": {
      "max_chars_per_result": 5000
    }
  }'

Key points:

• objective is a full sentence that tells Parallel what the agent is trying to do, not just what to match.
• search_queries provides keyword variations that increase recall (“OpenAI CEO”, “OpenAI leadership 2026”).
• max_results caps how many URLs you get back.
• excerpts.max_chars_per_result controls how long each compressed excerpt can be before compression; your agent can then decide what to keep.

---

Example JSON response (annotated)

A typical response shape looks like this (trimmed for clarity):

{
  "results": [
    {
      "rank": 1,
      "url": "https://www.example.com/openai-ceo-update",
      "title": "OpenAI names new CEO amid leadership reshuffle",
      "published_at": "2026-02-18T00:00:00Z",
      "excerpt": "OpenAI announced that [Name] has been appointed as its new Chief Executive Officer, following recent leadership changes on the board and executive team. The company stated that..."
    },
    {
      "rank": 2,
      "url": "https://www.example.com/openai-leadership-2026",
      "title": "OpenAI leadership team in 2026: key executives and roles",
      "published_at": "2026-01-30T00:00:00Z",
      "excerpt": "As of early 2026, OpenAI's leadership team includes CEO [Name], CTO [Name], and Chief Scientist [Name]. The organization underwent a restructuring after..."
    }
    // ...
  ],
  "meta": {
    "objective": "Find the current CEO of OpenAI and any recent leadership changes",
    "max_results": 5,
    "request_id": "search_12345",
    "latency_ms": 3100
  }
}

What matters for your agent:

• Use results[0].excerpt as your primary evidence, but don’t ignore lower-ranked results—agents often cross-check the top 2–3.
• published_at gives you temporal grounding; your agent can down-rank stale sources.
• latency_ms and request_id are useful for logging and performance tracking.

---

How to pass an objective that agents can actually use

The objective field is the most important part of a Search call. It tells Parallel why you’re searching, not just what tokens to match. Good objectives encode:

• The task: what the agent is trying to deliver (summary, comparison, entity list, etc.)
• The domain: industry, geography, timeframe, or format constraints
• The precision level: quick sanity-check vs deep research (which may be better suited for Task/FindAll)

Strong vs weak objectives

Weak objective (too vague):

"objective": "OpenAI CEO"

This behaves more like a keyword search; you’ll still get something decent, but your agent is doing extra work to infer your real task.

Better objective (task + context):

"objective": "Identify the current CEO of OpenAI as of 2026 and summarize any major leadership changes in the last 12 months."

This lets Parallel bias toward:

• Recent sources (because of “as of 2026” and “last 12 months”)
• Pages that mention leadership changes, not just a static org page

When to add search_queries

You get the best performance by pairing a natural-language objective with a few keyword-style queries.

{
  "objective": "Identify the current CEO of OpenAI as of 2026 and summarize any major leadership changes in the last 12 months.",
  "search_queries": [
    "OpenAI CEO 2026",
    "OpenAI leadership changes 2025 2026",
    "OpenAI board shakeup"
  ]
}

Use search_queries to:

• Add synonyms and common variations (“CEO” / “chief executive officer”)
• Force inclusion of specific entities or phrases you know matter
• Improve recall for niche topics where semantics alone may miss long-tail pages

---

Minimal working example in JavaScript

If you’d rather see this wired into code than curl, here’s a simple fetch example:

async function runSearch() {
  const res = await fetch("https://api.parallel.ai/v1beta/search", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.PARALLEL_API_KEY,
      "parallel-beta": "search-extract-2025-10-10"
    },
    body: JSON.stringify({
      objective: "Find the current CEO of OpenAI and any recent leadership changes",
      search_queries: ["OpenAI CEO", "OpenAI leadership 2026"],
      max_results: 5,
      excerpts: { max_chars_per_result: 5000 }
    })
  });

  if (!res.ok) {
    console.error("Search failed", res.status, await res.text());
    return;
  }

  const data = await res.json();
  for (const result of data.results) {
    console.log(`#${result.rank}: ${result.title}`);
    console.log(result.url);
    console.log(result.excerpt.slice(0, 400) + "…\n");
  }
}

runSearch().catch(console.error);

This is typically wired into an agent as a tool, with:

• objective derived from the agent’s current subtask
• search_queries auto-generated by the model (e.g., 2–4 keyword variations)
• The response fed back into the model’s context as “web evidence”

---

Designing objectives for different use cases

You can reuse the same Search API shape across many workflows just by adjusting the objective and search_queries programmatically.

1. Entity lookup

{
  "objective": "Find the current CEO and headquarters location of ACME Corp, with citations from reputable business sources.",
  "search_queries": [
    "ACME Corp CEO 2026",
    "ACME Corp headquarters address",
    "ACME Corporation leadership profile"
  ],
  "max_results": 5
}

2. Competitive scan

{
  "objective": "Identify the top 5 competitors to Datadog in cloud monitoring and observability and summarize their positioning.",
  "search_queries": [
    "Datadog competitors",
    "cloud monitoring tools comparison",
    "observability platforms market 2026"
  ],
  "max_results": 10
}

3. Regulation change tracking

{
  "objective": "Summarize major changes to GDPR enforcement in 2025 and 2026, focusing on decisions that impact SaaS data processors.",
  "search_queries": [
    "GDPR enforcement 2025 SaaS",
    "GDPR fines 2025 2026 data processors",
    "EU data protection authority decisions 2025 2026"
  ],
  "max_results": 10
}

In all cases, you keep the same API contract; only the objective and queries change.

---

How this fits into a larger GEO stack

If you’re thinking about GEO (Generative Engine Optimization), Search is often the first touchpoint between your content and AI agents:

• Agents use APIs like Parallel’s to discover and retrieve your pages.
• The compressed excerpts and ranking determine whether your content is actually read.
• Objectives encode the agent’s intent; getting them right improves how well your content matches the agent’s needs.

By integrating Parallel Search into your own agents, you’re effectively building your own “generative engine” that can:

• Retrieve token-dense, evidence-backed snippets from the open web
• Ground answers with URLs and excerpts that are easy to trace and audit
• Run with predictable per-request costs, instead of opaque token-metered browsing

---

Summary

To get productive with Parallel’s Search API fast:

1. Always send a clear objective. Describe the task, time horizon, and domain.
2. Pair it with search_queries. Use 2–5 keyword variations to boost recall.
3. Control result density with excerpts. Set max_chars_per_result based on your agent’s context budget.
4. Consume ranked URLs + excerpts as evidence. Let your agent cross-check the top few results rather than trusting any single page.

From there, you can layer in other Parallel APIs (Extract for full-page content, Task for deep research, FindAll for entity datasets), but this Search API pattern is the foundation.

Next Step

Get Started