Report missing data

Availability and access

A valid API key on an account with current paid access sends and checks a report, over REST or from an MCP client. Reporting needs no separate permission on the key, and a suspended account cannot report.

Report access needs current paid access on the account: a confirmed current paid subscription period, or a confirmed API payment within the last 30 days on the pay-as-you-go path. An account bound to a subscription is judged only on its subscription period, so a lapsed or reversed subscription does not fall back to an earlier payment. A key, a trial, or a test payment is not paid report access.

A report takes no extra payment, and sending or checking one does not use your plan request or byte allowance. The separate abuse limits still apply.

A report never changes the feed by itself. It creates an intake record and a validation job, and code checks run before any costly work.

Report through the API or your agent

A valid key on an account with current paid access submits and checks reports over REST and from an MCP client. Reporting needs no separate permission on the key.

Reporting never sets an account up on its own: a workspace without current paid access is refused with the paid-access error. REST and MCP report calls meet the same checks and the same limits.

1. Use an API key on the account that should own the report.
2. Send one sourceUrl and expectedRecord over REST, or call report_missing_data from an MCP client using that key.
3. Keep the report id the call returns, and check it later with GET /api/v1/data-reports/{reportId} or get_data_report.

Before you send a report

1. Check coverage for the place and record type. An empty search result alone does not prove that data is missing.
2. Check source health and remove optional search filters. Confirm the record date.
3. Open the public government source. Copy the record link and write one short sentence about what you expected to find.

Report a missing record

Send one sourceUrl and expectedRecord. Any valid API key can send this request; no report permission is needed, and the account must have current paid access. The description can have up to 1,000 characters, and the whole request can be at most 8 KiB. Use a public record link, not a sign-in or temporary download link.

Do not send API keys, passwords, wallet secrets, personal details, attachments, page dumps, or instructions for an agent to run. A source link and short description are enough.

curl --request POST 'https://aicdapi.com/api/v1/data-reports' \
  --header "Authorization: Bearer $AICD_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 461d4ca8-19ee-4d71-a4b4-215e15b72f78' \
  --data '{"sourceUrl":"https://city.example.gov/agendas/2026-09-10","expectedRecord":"The city council agenda published for September 10, 2026."}'

Keep the report ID

Save the report ID returned by the submit call. Use it to check progress. Follow the suggested next check time instead of polling in a loop.

If the submit response is lost, retry with the same Idempotency-Key and the same body. The retry returns the saved report without another job. A changed body with the same Idempotency-Key returns 409. Do not make a new report for the same gap just to get a faster result.

curl "https://aicdapi.com/api/v1/data-reports/$AICD_REPORT_ID" \
  --header "Authorization: Bearer $AICD_API_KEY"

Use your agent

An enabled MCP client can call report_missing_data and get_data_report with a valid key on an account with current paid access. The tools share the REST checks and the report limits, and they need no report permission. Report submission is a write action.

The report tool takes the same sourceUrl and expectedRecord, plus idempotencyToken for retries. The status tool takes reportId. Neither tool charges for a data query just to check a report.

When verifiedRecords contains a match, pass its itemId to get_agenda_item to read the record. That lookup uses the normal data-call access and payment rules. A verified record carries the item id, the source it was checked against, and its title when the source has one.

MCP failures use a tool result with isError and error.code. When error.retryAfterSeconds is present, wait that many seconds before a bounded retry. The HTTP status codes below describe the REST routes.

What happens next

Code checks run before any costly work. Unknown source sites and unclear records go to review. A report does not trigger an open web crawl, a model call, or an automatic production change.

A report can lead to a source fix, a search fix, or a clear reason why the record cannot be supplied. We do not promise a fix time or full coverage. Read the returned findings and next action.

• received or validating: the report is saved and code checks are pending or running.
• needs_review or investigating: the source needs review or the failed step needs to be found.
• fixing or verifying: a repair is in progress or being checked.
• resolved: the record can be found and a check is in place for the cause.
• not_missing: the data was present or the query did not match it.
• out_of_coverage: the place, record type, or date is outside supported coverage.
• unable_to_verify: the available source evidence did not prove the claim.

Limits and errors

• Submit up to 5 attempts per minute, 20 new reports per day, and 20 unresolved reports per customer. These limits apply across every key, REST, and MCP.
• Check status up to 30 times per minute per customer. Report limits are separate from paid data-call limits, and reports do not consume your plan allowance.
• Every report route also shares a limit of 60 attempts per minute per client IP address. Each report accepts at most 32 distinct retry tokens. Keep and reuse your original token.
• 400 means the input is not valid. 401 means the key is not valid. 403 means report access is denied. Check the account's status and its current paid access.
• 404 means the report was not found for this workspace. Check the report ID. 409 means the Idempotency-Key was used with a different body. 413 means the request is too large.
• 429 means a limit was reached. Wait for Retry-After, then retry with the same Idempotency-Key and body.
• 503 means a required check, the paid-access check, or the report queue is unavailable. Wait and retry with bounded backoff. Keep the same Idempotency-Key if the save result is unknown.

Privacy and other support

Only your customer account and authorized service staff can read your report. Reports are not added to public data feeds. Send only the public source and the short facts needed to check it.

For account trouble, payment trouble, or a report you cannot submit, email hello@aicdapi.com. Include the safe error code and report ID if you have one. Do not include a key or payment signature.