Requests

Methods for searching, retrieving, and creating FOIA requests.

RequestClient

class muckrock.requests.RequestClient

The request client allows access to search, list, create, and retrieve FOIA requests. Accessed generally as client.agencies. Refer to the getting started page to look at some examples of searching and filing requests.

list(self, **params)

List all FOIA requests with optional filtering and ordering. Available filters include:

  • user: Filter by the user ID of the person who filed the request.

  • title: Filter by the title of the request.

  • status: Filter by the status of the request (e.g., “submitted”, “ack”, “processed”).

  • embargo_status: Filter by the embargo status (e.g., “public”, “embargo”, “permanent”).

  • agency: Filter by the agency ID handling the request.

  • tags: Filter by tags associated with the request.

  • jurisdiction: Filter by the jurisdiction ID associated with the request.

  • search: An optional search term. For example, you can search for any request that mentions recipes.

Ordering options are available, including:

  • title: Sort by the request title.

  • status: Sort by the request status.

  • agency: Sort by the agency handling the request.

  • user: Sort by the user who filed the request.

  • datetime_submitted: Sort by the date the request was submitted.

  • datetime_done: Sort by the date the request was completed.

Ordering can be specified as either ascending (ordering=user) or descending (ordering=-user).

Parameters:

params – Query parameters to filter and order results, such as user, title, status, embargo_status, agency, tags, and jurisdiction, along with ordering.

Returns:

An APIResults object containing the list of FOIA requests.

retrieve(self, request_id)

Retrieve a specific FOIA request by its unique numerical identifier (ID).

Parameters:

request_id – The unique ID of the FOIA request to retrieve.

Returns:

A Request object representing the requested FOIA request.

create(self, title, requested_docs, organization, agencies, embargo_status='public', **kwargs)

Create a new FOIA request.

Parameters:

  • title – The title of the FOIA request. (Required)

  • requested_docs – A description of the documents being requested. (Required)

  • organization – The ID of the organization requesting the FOIA documents.

  • agencies – A list of agency IDs involved in the request. (Required)

  • embargo_status – The embargo status of the request (default is “public”).

  • kwargs – Additional parameters to be included in the request.

Returns:

A URL linking to the newly created FOIA request(s).

Raises:

ValueError if agencies is not a non-empty list.

Request

class muckrock.requests.Request

A representation of a single FOIA request.

str()

Return a string representation of the FOIA request, which is the request title.

get_communications(self)

Retrieve all communications associated with this FOIA request.

This method fetches all communications related to the specific FOIA request. If no communications are found, it returns an empty APIResults object.

Returns:

An APIResults object containing the list of communications.

id

The unique identifier for this FOIA request.

title

The title of the FOIA request.

requested_docs

A description of the documents being requested.

slug

The slug (URL identifier) for the FOIA request.

status

The current status of the FOIA request, represented as one of these values:

  • “submitted” - Processing

  • “ack” - Awaiting Acknowledgement

  • “processed” - Awaiting Response

  • “appealing” - Awaiting Appeal

  • “fix” - Fix Required

  • “payment” - Payment Required

  • “lawsuit” - In Litigation

  • “rejected” - Rejected

  • “no_docs” - No Responsive Documents

  • “done” - Completed

  • “partial” - Partially Completed

  • “abandoned” - Withdrawn

agency

The ID of the agency that the request was submitted to.

embargo_status

The embargo status of the request, indicating its visibility. Options include:

  • “public” - Public

  • “embargo” - Embargo (only available to paid professional users)

  • “permanent” - Permanent Embargo (only available to paid organizational members)

user

The user ID of the person who filed this request.

edit_collaborators

A list of user IDs who have been given edit access to this request.

read_collaborators

A list of user IDs who have been given view access to this request.

datetime_submitted

The timestamp of when this request was submitted.

datetime_updated

The date and time when the request was last updated.

datetime_done

The date and time when the request was completed, if applicable.

tracking_id

The tracking ID assigned to this request by the agency.

price

The cost of processing this request, if applicable.