> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Person Appearances

> List named participation in US federal meeting notices and optional news mentions with a city.

Searches US Federal Register meeting notices for explicit named participation at recognized public venues. Official schedules are observed records, not proof of attendance. Optional news mentions with a city are derived, never observed attendance. Congressional hearings and committee assignments are not searched. Read coverage before interpreting an empty answer.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**name** `string` *required*

Full name of the person. 2 to 150 characters.

**role** `string`

Role to narrow the name search. 2 to 100 characters.

**organization** `string`

Organization to narrow the name search. 2 to 150 characters.

**from** `string` *required*

First meeting or news-seen date, YYYY-MM-DD, inclusive.

**to** `string` *required*

Last meeting or news-seen date, YYYY-MM-DD, inclusive; at most one year after from.

**purpose** `string` *required*

Reason for researching this person’s public appearances. Up to 500 characters.

**include\_news** `boolean`

Also search recent news titles for a named US city; these are derived mentions, not attendance. Defaults to `false`.

**limit** `integer`

Most appearances to return. From 1 to 200. Defaults to `25`.

<Snippet file="audit-context-params.mdx" />

<Snippet file="cached-record-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `person_appearances`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.cached** `boolean`

`true` when the answer was served from OneShot's store of earlier lookups (or its own copy of a public dataset), `false` when the source was asked for this call

**data.fetched\_at** `string`

When the record was obtained from its source, as an ISO 8601 UTC time; equals `evidence.retrieved_at`

**data.evidence.source** `string`

The public body this call's data comes from: US Office of the Federal Register, by the input.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.appearances** `object[]`

Appearances.

**data.result.appearances\[].kind** `string`

Kind.

**data.result.appearances\[].observed** `object`

Observed.

**data.result.appearances\[].observed.title** `string`

Title.

**data.result.appearances\[].observed.at** `string`

At.

**data.result.appearances\[].observed.venue** `object`

Venue.

**data.result.appearances\[].observed.venue.building** `string | null`

Building. `null` when the source gives no value.

**data.result.appearances\[].observed.venue.city** `string | null`

City. `null` when the source gives no value.

**data.result.appearances\[].observed.role** `string | null`

Role. `null` when the source gives no value.

**data.result.appearances\[].observed.source\_url** `string`

Source url.

**data.result.appearances\[].derived** `object`

Derived.

**data.result.appearances\[].derived.news\_mention** `object`

News mention.

**data.result.appearances\[].derived.news\_mention.value** `object`

Value.

**data.result.appearances\[].derived.news\_mention.value.title** `string`

Title.

**data.result.appearances\[].derived.news\_mention.value.at** `string`

At.

**data.result.appearances\[].derived.news\_mention.value.venue** `object`

Venue.

**data.result.appearances\[].derived.news\_mention.value.venue.building** `string | null`

Building. `null` when the source gives no value.

**data.result.appearances\[].derived.news\_mention.value.venue.city** `string | null`

City. `null` when the source gives no value.

**data.result.appearances\[].derived.news\_mention.value.role** `string | null`

Role. `null` when the source gives no value.

**data.result.appearances\[].derived.news\_mention.value.source\_url** `string`

Source url.

**data.result.appearances\[].derived.news\_mention.rule** `string`

Rule.

**data.result.appearances\[].derived.news\_mention.from** `string[]`

From.

**data.result.total** `number`

Total.

**data.result.returned** `number`

Returned.

**data.result.truncated** `boolean`

Truncated.

**data.result.coverage** `object`

Coverage.

**data.result.coverage.federal\_register** `object`

Federal register.

**data.result.coverage.federal\_register.status** `string`

Status.

**data.result.coverage.federal\_register.read** `number`

Read.

**data.result.coverage.federal\_register.note** `string`

Note.

**data.result.coverage.federal\_register.candidates** `number | null`

Candidates. `null` when the source gives no value.

**data.result.coverage.news** `object`

News.

**data.result.coverage.news.status** `string`

Status.

**data.result.coverage.news.read** `number`

Read.

**data.result.coverage.news.note** `string`

Note.

**data.result.coverage.congressional** `object`

Congressional.

**data.result.coverage.congressional.status** `string`

Status.

**data.result.coverage.congressional.note** `string`

Note.

**data.result.coverage.limitation** `string`

Limitation.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/person-appearances \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "name": "Michael Bloomberg",
    "from": "2025-01-01",
    "to": "2025-01-31",
    "purpose": "Reporting on federal advisory committee recommendations."
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/person-appearances", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "name": "Michael Bloomberg",
    "from": "2025-01-01",
    "to": "2025-01-31",
    "purpose": "Reporting on federal advisory committee recommendations."
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/person-appearances', {
  name: 'Michael Bloomberg',
  from: '2025-01-01',
  to: '2025-01-31',
  purpose: 'Reporting on federal advisory committee recommendations.'
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "person_appearances",
    "result": {
      "appearances": [
        {
          "kind": "advisory_meeting",
          "observed": {
            "title": "Defense Innovation Board; Notice of Federal Advisory Committee Meeting",
            "at": "2025-01-13",
            "venue": {
              "building": "Pentagon",
              "city": "Washington"
            },
            "role": "welcome and opening remarks",
            "source_url": "https://www.federalregister.gov/documents/2025/01/17/2025-01204/defense-innovation-board-notice-of-federal-advisory-committee-meeting"
          },
          "derived": {}
        }
      ],
      "total": 1,
      "returned": 1,
      "truncated": true,
      "coverage": {
        "federal_register": {
          "status": "looked",
          "read": 2,
          "candidates": 8,
          "note": "US federal records only. Newest matching notices only, without a publication-date filter; meeting dates are filtered locally. At most two full notices (one with news). Only explicit named speaking participation, a single unambiguous meeting date and a recognized public venue are returned. Recognized buildings: Pentagon, White House, Eisenhower Executive Office Building, Herbert C. Hoover Building and National Academy of Sciences Building, each with Washington in the venue text. Titles containing numbers are omitted to avoid passing through street addresses. Scheduled participation is not proof of attendance. Other notices, venues and date formats may be missed."
        },
        "news": {
          "status": "not_searched",
          "read": 0,
          "note": "Optional recent GDELT DOC 2.0 news, not federal records or observed attendance. Only titles explicitly naming the subject and saying in Washington, New York, Boston, Chicago, Los Angeles, San Francisco, Seattle, Miami, Houston or Austin are used. Titles containing numbers are omitted. A named city may be unrelated to the subject; this is only a co-mention. The date is when the news index saw the article, not an event date. Publisher country is never a venue. Older windows may be unavailable."
        },
        "congressional": {
          "status": "not_searched",
          "note": "Congressional hearings and committee assignments are NOT searched. An empty result does not mean the person never testified."
        },
        "limitation": "US federal records only; optional news is separate, derived context. No private addresses."
      }
    },
    "evidence": {
      "source": "US Office of the Federal Register",
      "source_kind": "public",
      "retrieved_at": "2026-11-07T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-11-07T12:00:00.000Z"
        },
        {
          "retrieved_at": "2026-11-07T12:00:00.000Z"
        },
        {
          "retrieved_at": "2026-11-07T12:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* US federal records only. Newest matching notices only, without a publication-date filter; meeting dates are filtered locally. At most two full notices (one with news). Only explicit named speaking participation, a single unambiguous meeting date and a recognized public venue are returned. Recognized buildings: Pentagon, White House, Eisenhower Executive Office Building, Herbert C. Hoover Building and National Academy of Sciences Building, each with Washington in the venue text. Titles containing numbers are omitted to avoid passing through street addresses. Scheduled participation is not proof of attendance. Other notices, venues and date formats may be missed.
* Optional recent GDELT DOC 2.0 news, not federal records or observed attendance. Only titles explicitly naming the subject and saying in Washington, New York, Boston, Chicago, Los Angeles, San Francisco, Seattle, Miami, Houston or Austin are used. Titles containing numbers are omitted. A named city may be unrelated to the subject; this is only a co-mention. The date is when the news index saw the article, not an event date. Publisher country is never a venue. Older windows may be unavailable.
* Congressional hearings and committee assignments are NOT searched. An empty result does not mean the person never testified.
* Appearances put official fields under observed and news fields under derived.news\_mention.value with rule and from. News places come from title text, not publisher location.
* An empty looked result means no qualifying match in the records read. Unavailable means no evidence either way. Network failures fail the call. Coverage is never a complete appearance history.
* total counts qualifying appearances in the bounded records read, returned counts the output rows, and truncated also flags unread candidates or a full news page. Results are newest first. A purpose is required; refused purposes and suppressed subjects are checked before payment.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.