Streaming

Set Accept: text/event-stream for long-running Agent jobs.

curl -N https://api.ploid.com/v1/agent \
  -H "Authorization: Bearer $PLOID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "prompt": "Deeply research five seed accounts and find stage-matched lookalikes with evidence.",
    "max_acu": 2.4,
    "max_output_tokens": 18000
  }'

Public stream parts

The response is an AI SDK-compatible SSE stream. Parts you may encounter include:

Ignore unknown part types so clients remain forward compatible.

Tool activity

While the Agent works, each tool step emits a data-activity part with a friendly label suitable for direct display. When a step completes with a countable result set, the same part carries a count:

{
    "type": "data-activity",
    "data": {
        "label": "Searching people…",
        "tool": "search_people",
        "count": 497
    }
}

count is optional and only present on completed steps with countable results. Render label as-is; do not infer semantics from tool beyond grouping steps.

Structured result

When the request contains output_schema or output_contract, look for the event below. The fixed-contract payload is abridged here; use the full OpenAPI schema rather than treating this display sample as a complete object.

{
    "type": "data-structured-output",
    "data": {
        "structured_output": {
            "schema_version": "stage_aligned_lookalikes_v1",
            "decision_authority": "deterministic_validator",
            "result": {
                "answer": "...",
                "sources": [],
                "caveats": [],
                "companyMatches": {
                    "researchAsOfDate": "2026-08-14",
                    "seed": {
                        "canonicalName": "Ploy",
                        "domain": "ploy.ai"
                    },
                    "retainedCount": 0,
                    "retained": [],
                    "eligibleOverflow": [],
                    "analogues": [],
                    "rejected": []
                }
            }
        }
    }
}

For a caller-defined output_schema, structured_output is the value matching that schema. For the fixed stage contract, it is the versioned envelope above. See Structured outputs.

Reliability guidance

• Do not impose a short client timeout on deep research.
• Keep parsing until the stream terminates; a text answer can precede final usage metadata.
• Surface data-phase updates without exposing internal provider names.
• Accumulate text deltas in order.
• Preserve request IDs from response headers in logs.
• If no output arrives and the stream reports errors, fail the operation instead of returning an empty success.